Erros

Formato das respostas de erro e lista de códigos.

Erros usam códigos HTTP e têm sempre o mesmo formato. Escreva sua lógica sobre code, que é estável. message é um texto para pessoas e pode mudar.

code: identificador do erro.
message: descrição legível.
details: opcional. Em erros de validação, uma lista de { field, message }.

422 invalid_request

{
  "error": {
    "code": "invalid_request",
    "message": "Parâmetros inválidos.",
    "details": [
      {
        "field": "amount",
        "message": "Invalid input: expected number, received undefined"
      }
    ]
  }
}

Códigos

HTTP	code	Quando acontece
400	`invalid_json`	O corpo não é um JSON válido.
401	`unauthorized`	Chave de API ausente, inválida ou revogada.
402	`insufficient_funds`	Saldo disponível menor que valor mais tarifa.
403	`account_not_active`	Conta ainda não aprovada para operar em produção.
403	`account_blocked`	Conta bloqueada. Fale com o suporte.
403	`key_not_allowed`	A chave de produção não tem a permissão de saques.
403	`forbidden`	Ação não permitida no estado atual do recurso ou neste ambiente.
404	`not_found`	Recurso inexistente, de outra conta ou de outro ambiente.
409	`idempotency_conflict`	Idempotency-Key já usada com outros parâmetros.
409	`idempotency_in_progress`	A requisição original ainda está em andamento.
409	`conflict`	Conflito ao criar a cobrança. Repita a requisição.
422	`invalid_request`	Parâmetros inválidos. Veja details.
422	`amount_limit_exceeded`	Valor acima do limite permitido por transação.
422	`amount_below_minimum`	Saque crypto abaixo de US$ 5,00.
429	`rate_limited`	Limite de requisições atingido.
500	`internal_error`	Erro inesperado do nosso lado.
502	`provider_error`	Não foi possível processar a operação.
503	`provider_unavailable`	Serviço de pagamentos indisponível no momento.

O que repetir

4xx: não repita sem corrigir a requisição. A exceção é 429, que pode ser repetido depois de aguardar, e idempotency_in_progress.
5xx em saques ou timeout: repita com a mesma Idempotency-Key. Nunca crie um saque novo sem saber o que aconteceu com o anterior.
503 em cobranças: tente de novo. Pode repetir a mesma chave: uma cobrança que falhou ao ser criada libera a chave.