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

{
  "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 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

Leia o status HTTP

Ele já diz se o problema é de autenticação, validação, recurso inexistente ou limite de requisições.

Use `code` e `message`

Eles ajudam seu backend a decidir se deve corrigir a entrada, tentar de novo ou avisar seu time.

Guarde o `requestId`

Esse campo é a melhor chave para cruzar logs e localizar uma tentativa específica.

Decida se retry faz sentido

Retry costuma fazer sentido para 429 e 5xx. Em 4xx, normalmente o certo é corrigir o payload.

Como tratar sem dor

Sempre registre o requestId

Ele ajuda você a cruzar logs e investigar erros com mais rapidez.

Retry só quando faz sentido

429 e 5xx costumam pedir retry controlado. 4xx normalmente pedem correção da entrada.

Não esconda a mensagem

message e code ajudam seu backend a decidir a ação correta.

Idempotência reduz ruído

Em operações de criação, uma boa Idempotency-Key evita muitos problemas de duplicidade.

Próximos passos

Revisar autenticação

Se o erro estiver ligado a token, ambiente ou permissão, comece por aqui.

Voltar ao Quickstart

Use o exemplo base desta docs para comparar payload e headers com o seu código.

Ver webhooks

Se o problema estiver no recebimento de eventos, esta é a próxima página certa.

Precisa de ajuda para seguir?

Boas práticas

Veja o que vale a pena salvar em logs para investigar checkout, webhook e conciliação.

Glossário

Consulte definições rápidas de externalId, requestId, livemode e outros termos da docs.

Abrir o app

Revise chaves, ambiente e configuração da conta direto no app.

Fluxos do produto

Mais recursos

Erros

Erros

Formato do erro

Status HTTP mais comuns

Códigos `code` que a API emite

Como investigar sem dor

Como tratar sem dor

Sempre registre o requestId

Retry só quando faz sentido

Não esconda a mensagem

Idempotência reduz ruído

Próximos passos

Revisar autenticação

Voltar ao Quickstart

Ver webhooks

Precisa de ajuda para seguir?

Boas práticas

Glossário

Abrir o app

​Erros

​Formato do erro

​Status HTTP mais comuns

​Códigos code que a API emite

​Como investigar sem dor

​Como tratar sem dor

Sempre registre o requestId

Retry só quando faz sentido

Não esconda a mensagem

Idempotência reduz ruído

​Próximos passos

Revisar autenticação

Voltar ao Quickstart

Ver webhooks

​Precisa de ajuda para seguir?

Boas práticas

Glossário

Abrir o app

Erros

Formato do erro

Status HTTP mais comuns

Códigos `code` que a API emite

Como investigar sem dor

Como tratar sem dor

Próximos passos

Precisa de ajuda para seguir?