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ódigo | HTTP | Quando acontece |
|---|---|---|
VALIDATION_ERROR | 422 | Campo ausente, com formato errado, desconhecido ou fora do permitido; parâmetro ou cursor inválido. error.details aponta cada campo. |
INVALID_JSON | 400 | O corpo não é um JSON válido. |
NOT_FOUND | 404 | O recurso não existe nesta empresa e neste ambiente (ou é de outra empresa, ou do outro ambiente). |
ROUTE_NOT_FOUND | 404 | A rota não existe. Confira o método e o caminho. |
CONFLICT | 409 | A ação não cabe no estado de agora: link arquivado, pagamento já enviado, disputa decidida, beneficiário repetido, limite de arquivos. |
RATE_LIMITED | 429 | Mais de 1.200 chamadas por minuto com a chave. Espere error.details.retryAfterSeconds. |
Chave e empresa
| Código | HTTP | Quando acontece |
|---|---|---|
API_KEY_INVALID | 401 | Chave ausente, fora do formato, desconhecida, revogada ou vencida. |
API_KEY_SCOPE | 403 | A chave não tem o nível pedido no recurso. |
IP_NOT_ALLOWED | 403 | O IP da chamada não está na lista da chave. |
MERCHANT_NOT_ACTIVE | 403 | Chave de produção de empresa que ainda não está ativa. Use o ambiente de teste. |
MERCHANT_SUSPENDED | 403 | Empresa suspensa: a API recusa as chamadas. Fale com o suporte. |
MERCHANT_BLOCKED | 403 | Empresa bloqueada: a API recusa as chamadas. Fale com o suporte. |
Repetição
| Código | HTTP | Quando acontece |
|---|---|---|
IDEMPOTENCY_KEY_REQUIRED | 400 | Faltou a Idempotency-Key numa rota que exige. |
IDEMPOTENCY_KEY_REUSED | 409 | A Idempotency-Key já foi usada nesta rota com outro corpo. |
IDEMPOTENCY_REQUEST_IN_PROGRESS | 409 | O primeiro pedido com a mesma chave ainda está rodando. Espere e repita. |
EXTERNAL_ID_CONFLICT | 409 | O externalId já existe: na cobrança, com outro conteúdo; no pagamento, sempre. |
Cobranças e pagamentos
| Código | HTTP | Quando acontece |
|---|---|---|
AMOUNT_TOO_LOW | 422 | O valor não cobre a tarifa (cobrança ou link de valor fixo). |
PAYMENT_METHOD_UNAVAILABLE | 422 | O 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_ENABLED | 422 | A moeda não está habilitada para a sua empresa. Peça ao suporte para habilitar. |
CHARGE_NOT_OPEN | 409 | A cobrança não está pendente: não dá para cancelar. error.details.status diz o status. |
INSUFFICIENT_BALANCE | 422 | O disponível não cobre o pagamento ou a devolução (com a tarifa). |
RISK_DECLINED | 422 | Recusado pela análise de risco. O motivo não é informado. |
Devoluções e disputas
| Código | HTTP | Quando acontece |
|---|---|---|
CHARGE_NOT_REFUNDABLE | 409 | A cobrança não está paga ou já foi devolvida por inteiro. |
CHARGE_DISPUTED | 409 | A cobrança está em disputa (MED): devolução só depois da decisão. |
REFUND_UNAVAILABLE | 422 | O provedor que recebeu não devolve pela plataforma, ou só aceita uma devolução por cobrança. |
REFUND_WINDOW_EXPIRED | 422 | Passou o prazo de devolução, contado do pagamento. |
REFUND_EXCEEDS_REFUNDABLE | 422 | O valor passa do que ainda pode ser devolvido (error.details.refundable). |
DISPUTE_EVIDENCE_CLOSED | 409 | Passou o prazo da disputa para evidências, defesa e explicação. |
Disponibilidade
| Código | HTTP | Quando acontece |
|---|---|---|
CHARGES_DISABLED | 503 | Recebimentos pausados pela plataforma. Repita mais tarde, com a mesma Idempotency-Key. |
PAYOUTS_DISABLED | 503 | Pagamentos pausados pela plataforma. Repita mais tarde, com a mesma Idempotency-Key. |
REFUNDS_DISABLED | 503 | Devoluções pausadas pela plataforma. Repita mais tarde, com a mesma Idempotency-Key. |
PROVIDER_UNAVAILABLE | 503 | Nenhum provedor disponível para o método agora. Repita com a mesma Idempotency-Key. |
INTERNAL_ERROR | 500 | Erro 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.