# Erros e limites da API REST

> A API do Bot do Afiliado responde 401 sem chave, 403 insufficient_scope quando o nível não cobre o endpoint e 400 com texto pronto para o usuário; no lote do /convert-links, o limite é 150 URLs e o que passa disso é ignorado.

- URL: https://botdoafiliado.com/docs/api/erros-e-limites/
- Publicado em: 2026-05-29
- Atualizado em: 2026-10-24
- Índice da documentação para IA: https://botdoafiliado.com/llms.txt

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](/docs/api/autenticacao/)**.

## 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](/docs/api/script-do-site/)**. |
| 403 | `insufficient_scope` | A chave é válida, mas o **[nível](/docs/api/autenticacao/#níveis-de-permissão)** 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`/`ok` antes de usar `affiliate_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.

## Perguntas frequentes

### O que acontece se eu mandar mais de 150 URLs no /convert-links?

A API converte as 150 primeiras e ignora o resto, sem erro. Divida listas maiores em lotes de até 150.

### O erro de conversão da API REST é problema de scraping do produto?

Não. Significa que não há rota ou conversor ativo para a loja, ou faltam credenciais do plugin. O texto do erro diz isso em português.

### O que é 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.

### Qual o limite de URLs por requisição na API REST do Bot do Afiliado?

150 no modo batch do /convert-links. No /amazon-prices, 10 ASINs por chamada.