Erros

Formato do erro, códigos HTTP e o que fazer em cada caso.

Formato do erro#

Quando algo falha, data vem null e error é preenchido. Trate sempre pelo code, que é estável — a message é texto para humanos e pode mudar.

Guarde o request_id nos seus logs. Ele é o que permite localizar exatamente a requisição quando você abrir um chamado com o suporte.

422corpo do erro

{
  "data": null,
  "error": {
    "code": "insufficient_balance",
    "message": "Saldo insuficiente para este saque.",
    "details": { "available_centavos": 3200 }
  },
  "request_id": "req_51d0be7a"
}

Códigos HTTP#

Status	Significado	O que fazer
400	Requisição malformada	Confira o JSON enviado.
401	Não autenticado	Chave ausente, inválida ou revogada.
403	Sem permissão	A chave não tem o escopo, ou a conta ainda não foi aprovada.
404	Não encontrado	O id não existe ou não pertence a esta conta.
409	Conflito de estado	A operação não é válida no estado atual do recurso.
422	Regra de negócio	Os dados são válidos, mas a regra não permite. Leia o code.
429	Limite atingido	Aguarde e repita com a mesma Idempotency-Key.
5xx	Falha nossa	Repita com backoff. Se persistir, abra um chamado com o request_id.

Erro não é motivo para recriar

Antes de criar uma nova cobrança após um erro, consulte a original. Em muitos casos ela foi criada com sucesso e apenas a resposta se perdeu.