Dois formatos de erro
A API retorna erros em JSON, em um de dois formatos.Erro geral
Um único campodetail com a mensagem:
Erro de validação
Um objeto onde cada chave é o campo rejeitado e o valor é a lista de problemas daquele campo:As mensagens são retornadas em português (Brasil). Não use o texto da mensagem como regra de negócio — trate pelo código de status e, quando for erro de validação, pelo nome do campo.
Códigos de status
Casos que confundem
401 vs 403
401 vs 403
401— a API não sabe quem você é: o token está ausente, malformado ou expirou.403— a API sabe quem você é, mas sua chave não tem o escopo necessário. Por exemplo, chamarPOST /public_api/products/com um token que só temread.
404 em recurso que existe
404 em recurso que existe
Todos os endpoints filtram pelos dados da sua conta. Consultar um recurso que pertence a outro produtor retorna
404, não 403 — isso é intencional, para não revelar a existência do recurso.Token expirado no meio de um lote
Token expirado no meio de um lote
O token tem validade limitada (campo
expires_in) e não existe endpoint de renovação. Ao receber 401 durante um processamento longo, solicite um novo token e repita a requisição.Erro 5xx numa cobrança
Erro 5xx numa cobrança
Respostas
5xx não são armazenadas pela idempotência. Repita a requisição com o mesmo X-Idempotency-Key: se a cobrança original tiver sido criada, você recebe a resposta original em vez de uma duplicata.Próximos passos
Autenticação
Escopos, tokens e expiração
Limites de Requisição
Como reagir ao 429