Erros

Formato unificado, todos os códigos e como resolver cada um.

Formato de erro

Todos os erros seguem o mesmo envelope JSON. O campo error.code é a chave para identificar o problema programaticamente.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Saldo disponível insuficiente para esta transferência",
    "request_id": "req_2f8a3b1c"
  }
}

O header X-Request-ID na resposta também carrega o mesmo request_id. Inclua-o em reportes de suporte para rastreio.

Tabela de erros — autenticação

Código	HTTP	Causa e solução
INVALID_CREDENTIALS	401	key_id não encontrado ou key_secret incorreto. Verifique as credenciais no painel.
CREDENTIAL_INACTIVE	403	A chave de API está com status INATIVA ou REVOGADA. Ative uma nova chave no painel.
IP_NOT_AUTHORIZED	403	O IP de origem não está na whitelist da chave. Adicione o IP no painel ou remova a restrição.
MISSING_TOKEN	401	Header Authorization ausente. Inclua: Authorization: Bearer <access_token>
INVALID_TOKEN	401	Token expirado, malformado ou assinatura inválida. Obtenha um novo token via POST /v1/auth/token ou /v1/auth/refresh.
INSUFFICIENT_SCOPE	403	O token não tem o scope necessário para este endpoint. Verifique os scopes da chave no painel.
INVALID_REFRESH_TOKEN	401	Refresh token não encontrado (expirado após 7 dias ou já revogado). Autentique novamente.

Tabela de erros — validação

Código	HTTP	Causa e solução
VALIDATION_ERROR	400	Body inválido. O campo details (quando presente) lista os campos com erro.
MISSING_IDEMPOTENCY_KEY	400	Header Idempotency-Key ausente em requisição POST. Inclua um UUID v4 único.
AMOUNT_BELOW_MINIMUM	422	Valor abaixo do mínimo configurado para a conta. Verifique os limites em /v1/balance.
AMOUNT_ABOVE_MAXIMUM	422	Valor acima do máximo configurado para a conta.
SPLIT_EXCEEDS_100	422	A soma dos percentuais de split ultrapassa 100%. Revise a distribuição.
INSUFFICIENT_BALANCE	422	Saldo disponível menor que o valor da transferência. Aguarde confirmação de cobranças pendentes.

Tabela de erros — cobranças e transferências

Código	HTTP	Causa e solução
CHARGE_NOT_FOUND	404	Cobrança não encontrada ou não pertence a esta conta.
CHARGE_NOT_CANCELLABLE	409	Cobrança não pode ser cancelada — status diferente de PENDING. Verifique o status atual.
CHARGE_FAILED	502	Adquirente retornou erro ao gerar a cobrança. Tente novamente com nova Idempotency-Key em caso de retry.
TRANSFER_NOT_FOUND	404	Transferência não encontrada ou não pertence a esta conta.
NOT_IMPLEMENTED	501	Funcionalidade ainda não disponível (ex: GET /v1/pix/keys quando chaves Pix não estão cadastradas).

Tabela de erros — rate limit

Código	HTTP	Causa e solução
RATE_LIMIT_EXCEEDED	429	Mais de 100 requisições por minuto para esta chave. Aguarde o valor em Retry-After (segundos) antes de tentar novamente.