A API do Bot do Afiliado usa três respostas de erro na chamada inteira: 401 sem chave válida, 403 insufficient_scope quando o nível da chave não cobre o endpoint e 400 para corpo inválido ou conversão impossível. No lote do /convert-links, cada item falha sozinho, com ok: false. Veja também autenticação.
Erros da chamada
| HTTP | error |
Significado |
|---|---|---|
| 401 | invalid_api_key (ex.: /execute) ou o texto “API key obrigatória (header X-API-Key)…” (/convert e /convert-links) |
X-API-Key ausente ou inválida. No navegador, use uma Embed Key. |
| 403 | insufficient_scope |
A chave é válida, mas o nível dela não cobre esse endpoint (ex.: chave de Leitura chamando /convert-links). |
| 400 | url ou urls é obrigatório |
O corpo do /convert-links não trouxe nenhum link. |
| 400 | texto em português | Conversão impossível no /convert (ex.: “Ainda não tenho uma integração ativa para esse site…”) ou refresh fora do Mercado Livre. |
| 5xx | erro inesperado | Falha de rede, indisponibilidade da loja ou exceção não tratada. |
Erros por item (lote)
No modo batch do /convert-links, falha de conversão não derruba a chamada: o item traz ok: false, affiliate_url: null, final_url: null e error. O error vem em texto pronto para mostrar ao usuário, com uma exceção:
conversion_returned_source_url: o conversor devolveu o próprio link de origem, sem prova de que a sua atribuição está nele. A API recusa em vez de entregar um link que não paga comissão. Amazon pode reaproveitar um link já gerado para a tag ativa.
No /execute, parcelamento incompleto ou inválido em installments_overrides volta como status: "error" com error: "invalid_installments".
Textos que você pode encontrar: “Não consegui ler esse link…” (URL incompleta), “Esse link não parece seguro…” (destino recusado), “O Mercado Livre não permite link de afiliado para esta página…” (oferta, categoria ou cupom do ML) e o de integração inativa.
Limites
| Limite | Valor |
|---|---|
URLs por chamada no /convert-links |
150; as que passam disso são ignoradas, sem erro |
history_limit no /product |
1 a 50 (padrão 10); fora disso, o valor é trazido para a faixa |
ASINs por chamada no /amazon-prices |
10 |
Imagem na arte do /promo-card |
4 MiB; a foto original (raw: true), 8 MiB; SVG recusado |
| Resposta repetida | a mesma URL devolve a mesma resposta por 60 segundos no mesmo data center |
Boas práticas
- Trate
success/okantes de usaraffiliate_url/final_url. - Repita só os itens que falharam e use lotes menores em caso de timeout.
- Implemente backoff em caso de 5xx.
- Não exponha a API key no cliente: no site, use a Embed Key travada por domínio.