Guia
Erros e limites
Todo erro volta como JSON com um detail que explica o que houve.
A regra de ouro da cobrança nas falhas: falha nossa nunca cobra; tentativa feita
sempre cobra.
Formato do erro
{ "detail": "Rate limit exceeded" }Códigos
| Código | Quando | Cobra? |
|---|---|---|
401 | Chave ausente, desconhecida, revogada ou desativada. | não |
403 | Chave válida, mas sem o escopo buybox:read. | não |
404 | Marketplace que não atendemos. Nada foi tentado. | não |
422 | Lote vazio, acima de 200 itens, ou month fora do formato YYYY-MM. | não |
429 | Acima do rate limit da chave (header Retry-After em segundos). | não |
501 | Rota reservada, ainda não implementada (fase 2). | não |
503 | Indisponibilidade nossa. Nada foi cobrado; repita a chamada. | não |
Item que não tem buybox, ou que não monitoramos, não é
404: é 200 com status: EMPTY, e é cobrado - a tentativa
aconteceu. Só o marketplace dá 404. Veja o guia do buybox.
Rate limit
O limite é por chave: 120 requests por minuto por padrão, ajustável no seu
contrato. Acima dele a API responde 429 com o header Retry-After
dizendo em quantos segundos a janela reabre.
HTTP/1.1 429 Too Many Requests
Retry-After: 37
{ "detail": "Rate limit exceeded" }- Respeite o
Retry-After- repetir antes só mantém a janela cheia. - Um lote de 200 itens é 1 request no rate limit; 200 GETs são 200. Para sortimento, use o lote.
Como tratar 503
O 503 na leitura significa que preferimos não servir o dado a servir sem
registrar a cobrança - nada foi cobrado e nada foi entregue. Repita a chamada; com backoff
simples (1s, 2s, 4s) é suficiente.