Primeiros passos

Erros

Formato dos erros, códigos de status e quando tentar de novo.

Os erros usam códigos de status HTTP padrão e sempre retornam o mesmo envelope JSON, com um código estável e legível por máquina.

Formato do erro#

{
  "error": {
    "code": "rateLimited",
    "message": "Rate limit exceeded",
    "retryAfter": 12
  }
}

error.code é estável e seguro para usar em condicionais. error.message é uma dica legível para humanos e pode mudar. Alguns erros trazem campos extras: retryAfter para limites de taxa, reason para cotas e restrições de plano, issues para erros de validação.

Códigos de erro#

Status	Código	Significado	Tentar de novo?
400	validation	Um parâmetro ou o corpo da requisição é inválido; veja `error.issues`.	Não
401	unauthorized	A chave de API está ausente, malformada ou revogada.	Não
402	planRequired	O seu plano não inclui acesso à API ou a este recurso.	Não
403	forbidden	A requisição não é permitida.	Não
404	notFound	O token ainda não foi escaneado ou a carteira ainda não foi perfilada.	Mais tarde
409	conflict	A requisição entra em conflito com o estado atual.	Não
429	rateLimited	Requisições demais por minuto, ou a cota mensal se esgotou.	Sim
500	generic	Algo deu errado do nosso lado.	Sim
503	unavailable	Manutenção em andamento ou provedor de dados sem capacidade.	Mais tarde

Erros de validação#

Parâmetros inválidos retornam 400 com uma lista de issues que apontam para o campo com problema.

400

{
  "error": {
    "code": "validation",
    "message": "Invalid input",
    "issues": [
      {
        "path": "pageSize",
        "message": "Invalid input"
      }
    ]
  }
}