> ## Documentation Index
> Fetch the complete documentation index at: https://docs.troqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Erros
> Veja como a API responde quando alguma coisa dá errado.
# Erros
Quando uma chamada falha, a TroqPay responde com um status HTTP coerente com o problema e um corpo de erro padronizado.
Isso facilita investigar o problema e decidir o próximo passo.
## Formato do erro
```json theme={null}
{
"error": {
"type": "validation_error",
"code": "invalid_request_body",
"message": "Number must be greater than 0",
"requestId": "req_4a8b3c1d5e6f2a9b0c1d2e3f"
}
}
```
As mensagens vêm em inglês — é o que a API emite literalmente. A narrativa em torno fica em PT-BR para ajudar a interpretar.
## Status HTTP mais comuns
| HTTP | Quando aparece | O que fazer agora |
| ----- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `400` | Corpo inválido ou JSON malformado | Revise os tipos e a estrutura do JSON |
| `401` | Chave ausente, mal formatada, inválida ou revogada | Confira o header `Authorization` |
| `403` | Conta sem acesso a produção, conta suspensa ou operações temporariamente bloqueadas | Veja `code` para detalhe e [Produção](/production) para o caminho de aprovação |
| `404` | Recurso não encontrado | Confirme o ID enviado |
| `409` | A mesma `Idempotency-Key` foi usada com um corpo diferente | Use uma chave nova ou envie o mesmo corpo |
| `422` | Regra de negócio não atendida (`expiresIn`, etc.) | Veja `code` para detalhe |
| `429` | Limite de requisições excedido | Faça retry com backoff exponencial |
| `503` | Provedor temporariamente indisponível | Faça retry — não é problema do seu payload |
## Códigos `code` que a API emite
| `code` | Categoria | HTTP | Como agir |
| -------------------------------- | ---------------- | ---- | ------------------------------------------------------------------------------------------------------ |
| `invalid_json` | validação | 400 | Corpo da requisição não é JSON válido. Confira como você está serializando. |
| `invalid_request_body` | validação | 400 | Algum campo violou tipo, tamanho ou regra de pelo-menos-um. A `message` traz o detalhe. |
| `unauthorized` | autenticação | 401 | Chave ausente, mal formatada, inválida ou revogada. |
| `forbidden` | autorização | 403 | Conta sem `APPROVED` para produção. |
| `api_key_scope_forbidden` | autorização | 403 | A chave não tem permissão para o recurso chamado. |
| `account_suspended` | autorização | 403 | Conta suspensa. Acesse o app ou entre em contato com o suporte. |
| `live_operations_blocked` | autorização | 403 | Operações em produção temporariamente bloqueadas. Acesse o app ou entre em contato com o suporte. |
| `test_withdrawals_not_supported` | autorização | 403 | Saques estão disponíveis somente em produção. |
| `withdrawal_readiness_required` | autorização | 403 | A conta ainda precisa completar a configuração necessária para saques. |
| `withdrawals_blocked` | autorização | 403 | Saques temporariamente bloqueados para a conta. |
| `idempotency_key_required` | validação | 400 | O header `Idempotency-Key` é obrigatório para criar saques pela API. |
| `idempotency_conflict` | conflito | 409 | A mesma `Idempotency-Key` foi reutilizada com outro corpo. |
| `invalid_expires_in` | regra (checkout) | 422 | `expiresIn` fora do intervalo 900-86400. |
| `invalid_amount` | regra (saque) | 422 | Valor inválido para o saque solicitado. |
| `insufficient_balance` | regra (saque) | 422 | Saldo disponível insuficiente para o saque solicitado. |
| `quote_unavailable` | regra (saque) | 422 | Cotação indisponível para o saque solicitado. Tente novamente depois. |
| `checkout_not_found` | not found | 404 | O `checkoutId` não existe ou não pertence à sua conta. |
| `withdrawal_not_found` | not found | 404 | O `withdrawalId` não existe ou não pertence à sua conta. |
| `provider_unavailable` | provedor | 503 | Provedor de pagamentos temporariamente indisponível. Retry seguro. |
| `rate_limit_exceeded` | limite | 429 | Limite de requisições. Implemente backoff (veja o header `Retry-After`) e não repita em loop apertado. |
## Como investigar sem dor
Ele já diz se o problema é de autenticação, validação, recurso inexistente ou limite de requisições.
Eles ajudam seu backend a decidir se deve corrigir a entrada, tentar de novo ou avisar seu time.
Esse campo é a melhor chave para cruzar logs e localizar uma tentativa específica.
Retry costuma fazer sentido para `429` e `5xx`. Em `4xx`, normalmente o certo é corrigir o payload.
## Como tratar sem dor
Ele ajuda você a cruzar logs e investigar erros com mais rapidez.
`429` e `5xx` costumam pedir retry controlado. `4xx` normalmente pedem correção da entrada.
`message` e `code` ajudam seu backend a decidir a ação correta.
Em operações de criação, uma boa `Idempotency-Key` evita muitos problemas de duplicidade.
## Próximos passos
Se o erro estiver ligado a token, ambiente ou permissão, comece por aqui.
Use o exemplo base desta docs para comparar payload e headers com o seu código.
Se o problema estiver no recebimento de eventos, esta é a próxima página certa.
## Precisa de ajuda para seguir?
Veja o que vale a pena salvar em logs para investigar checkout, webhook e conciliação.
Consulte definições rápidas de `externalId`, `requestId`, `livemode` e outros termos da docs.
Revise chaves, ambiente e configuração da conta direto no app.