Erros

A API usa os códigos HTTP no sentido convencional: 2xx deu certo, 4xx é problema na requisição, 5xx é problema no servidor.

Códigos

Código	Significado	O que fazer
200	OK	—
400	Requisição malformada	JSON inválido ou parâmetro obrigatório ausente. Corrija e repita.
401	Não autenticado	Chave ausente, inválida ou revogada. Confira o header api_access_token.
403	Sem permissão	A chave é válida, mas o usuário dono dela não tem acesso ao recurso.
404	Não encontrado	O recurso não existe ou não pertence a esta conta. Confira o ID da conta no caminho.
422	Não processável	A requisição está bem formada, mas os dados falharam na validação. O corpo diz qual campo.
429	Limite excedido	Espere e repita com backoff. Veja Limites de requisição.
500	Erro no servidor	Repita depois. Se persistir, fale com o suporte.

401 e 403 são coisas diferentes

• 401 — quem é você? A chave não foi reconhecida.
• 403 — sei quem você é, mas não pode. A chave vale, o usuário dono dela é que não tem permissão. Repetir não resolve: ou o usuário ganha a permissão, ou a chave precisa ser de outro usuário.

404 costuma ser conta errada

Quase todo endpoint é escopado por conta (/api/v1/accounts/{account_id}/…). Pedir um recurso de outra conta devolve 404, não 403 — de propósito, para não revelar que o recurso existe. Se um ID que você sabe que existe devolve 404, confira o account_id do caminho antes de procurar o bug em outro lugar.

Erros de validação

O 422 costuma trazer o motivo no corpo:

{
  "message": "Validation failed: Name can't be blank"
}

Alguns endpoints devolvem os erros por campo:

{
  "errors": {
    "email": ["já está em uso"]
  }
}

O formato não é uniforme em toda a API. Ao tratar erros de forma genérica, prefira o código HTTP e use o corpo apenas para exibir a mensagem.

Ao integrar

• Trate 429 e 5xx com retry e backoff; não repita 4xx — repetir uma requisição inválida só gasta cota.
• Registre o corpo da resposta quando der erro: ele quase sempre diz o que faltou.
• Não deduza sucesso pelo corpo. Cheque o status.