Erros e limites

O formato de todo erro, os códigos que sua integração deve tratar e o limite de chamadas.

Formato

Todo erro da API tem o mesmo corpo:

{
  "code": "invalid_parameter",
  "detail": "\"page_size\" vai até 100."
}

code é para o seu programa. É estável: um código publicado não muda de nome nem some.
detail é para pessoas. Pode mudar de redação a qualquer momento: não compare texto.

O que fazer com cada um

HTTP	code	O que fazer
400	`invalid_parameter`	Erro do seu lado: corrija a chamada. O `detail` diz qual parâmetro. Não repita igual
401	`missing_api_key`, `invalid_api_key`	Confira o cabeçalho e o ambiente. Não repita em laço
401	`api_key_revoked`, `api_key_expired`	A chave parou de valer. Peça uma nova ao administrador do cliente
403	`insufficient_scope`	A chave não tem o escopo do endpoint. Peça o acesso
403	`module_disabled`	O cliente não tem o módulo contratado
403	`store_not_allowed`	A chave está restrita a algumas lojas e você pediu outra
404	`not_found`	Rota inexistente. Confira o caminho e a versão
405	`method_not_allowed`	Método HTTP errado para a rota
409	`idempotency_key_reused`	Você repetiu um `Idempotency-Key` com outro corpo. Gere uma chave nova para cada lote diferente
429	`rate_limited`	Espere os segundos do cabeçalho `Retry-After` e repita
500	`internal_error`	Repita com espera crescente. Se persistir, fale com o suporte informando hora e prefixo da chave

A lista completa, sempre atualizada, está na referência.

Limite de chamadas

Cada chave pode fazer 120 chamadas por minuto. Acima disso, a resposta é 429 rate_limited com o cabeçalho Retry-After, em segundos.

Para ficar longe do limite:

use page_size=100 em vez de muitas páginas pequenas;
nos envios, mande lotes cheios (até 500 itens por chamada) em vez de um item por chamada;
use updated_since em vez de ler tudo de novo: Paginação e sincronização;
não rode várias cópias do mesmo laço em paralelo com a mesma chave.

Repetir com segurança

Repita só o que pode dar certo na segunda vez: 429, 500, timeout e erro de rede. Use espera crescente, por exemplo 1 s, 2 s, 4 s e 8 s, e pare depois de algumas tentativas. Erros 4xx (menos o 429) não se resolvem repetindo.