Códigos

Os valores de error.code que a API pública devolve, com o status HTTP de cada um. Compare pelo código; se aparecer um que o seu sistema não conhece, trate pelo status.

Pedido

Códigos de erro
CódigoHTTPQuando acontece
VALIDATION_ERROR422Campo ausente, com formato errado, desconhecido ou fora do permitido; parâmetro ou cursor inválido. error.details aponta cada campo.
INVALID_JSON400O corpo não é um JSON válido.
NOT_FOUND404O recurso não existe nesta empresa e neste ambiente (ou é de outra empresa, ou do outro ambiente).
ROUTE_NOT_FOUND404A rota não existe. Confira o método e o caminho.
CONFLICT409A ação não cabe no estado de agora: link arquivado, pagamento já enviado, disputa decidida, beneficiário repetido, limite de arquivos.
RATE_LIMITED429Mais de 1.200 chamadas por minuto com a chave. Espere error.details.retryAfterSeconds.

Chave e empresa

Códigos de erro
CódigoHTTPQuando acontece
API_KEY_INVALID401Chave ausente, fora do formato, desconhecida, revogada ou vencida.
API_KEY_SCOPE403A chave não tem o nível pedido no recurso.
IP_NOT_ALLOWED403O IP da chamada não está na lista da chave.
MERCHANT_NOT_ACTIVE403Chave de produção de empresa que ainda não está ativa. Use o ambiente de teste.
MERCHANT_SUSPENDED403Empresa suspensa: a API recusa as chamadas. Fale com o suporte.
MERCHANT_BLOCKED403Empresa bloqueada: a API recusa as chamadas. Fale com o suporte.

Repetição

Códigos de erro
CódigoHTTPQuando acontece
IDEMPOTENCY_KEY_REQUIRED400Faltou a Idempotency-Key numa rota que exige.
IDEMPOTENCY_KEY_REUSED409A Idempotency-Key já foi usada nesta rota com outro corpo.
IDEMPOTENCY_REQUEST_IN_PROGRESS409O primeiro pedido com a mesma chave ainda está rodando. Espere e repita.
EXTERNAL_ID_CONFLICT409O externalId já existe: na cobrança, com outro conteúdo; no pagamento, sempre.

Cobranças e pagamentos

Códigos de erro
CódigoHTTPQuando acontece
AMOUNT_TOO_LOW422O valor não cobre a tarifa (cobrança ou link de valor fixo).
PAYMENT_METHOD_UNAVAILABLE422O método ou a moeda não está disponível (ex.: moeda que não é a do PIX) ou está em manutenção.
CURRENCY_NOT_ENABLED422A moeda não está habilitada para a sua empresa. Peça ao suporte para habilitar.
CHARGE_NOT_OPEN409A cobrança não está pendente: não dá para cancelar. error.details.status diz o status.
INSUFFICIENT_BALANCE422O disponível não cobre o pagamento ou a devolução (com a tarifa).
RISK_DECLINED422Recusado pela análise de risco. O motivo não é informado.

Devoluções e disputas

Códigos de erro
CódigoHTTPQuando acontece
CHARGE_NOT_REFUNDABLE409A cobrança não está paga ou já foi devolvida por inteiro.
CHARGE_DISPUTED409A cobrança está em disputa (MED): devolução só depois da decisão.
REFUND_UNAVAILABLE422O provedor que recebeu não devolve pela plataforma, ou só aceita uma devolução por cobrança.
REFUND_WINDOW_EXPIRED422Passou o prazo de devolução, contado do pagamento.
REFUND_EXCEEDS_REFUNDABLE422O valor passa do que ainda pode ser devolvido (error.details.refundable).
DISPUTE_EVIDENCE_CLOSED409Passou o prazo da disputa para evidências, defesa e explicação.

Disponibilidade

Códigos de erro
CódigoHTTPQuando acontece
CHARGES_DISABLED503Recebimentos pausados pela plataforma. Repita mais tarde, com a mesma Idempotency-Key.
PAYOUTS_DISABLED503Pagamentos pausados pela plataforma. Repita mais tarde, com a mesma Idempotency-Key.
REFUNDS_DISABLED503Devoluções pausadas pela plataforma. Repita mais tarde, com a mesma Idempotency-Key.
PROVIDER_UNAVAILABLE503Nenhum provedor disponível para o método agora. Repita com a mesma Idempotency-Key.
INTERNAL_ERROR500Erro do nosso lado, sem detalhe. Repita com a mesma Idempotency-Key e, se continuar, mande o X-Request-Id ao suporte.

Veja também

O envelope e o que vem em error.details estão em Formato de erro; os erros de cada rota, na página dela.