Skip to main content

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

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

HTTPQuando apareceO que fazer agora
400Corpo inválido ou JSON malformadoRevise os tipos e a estrutura do JSON
401Chave ausente, mal formatada, inválida ou revogadaConfira o header Authorization
403Conta sem acesso a produção, conta suspensa ou operações temporariamente bloqueadasVeja code para detalhe e Produção para o caminho de aprovação
404Recurso não encontradoConfirme o ID enviado
409A mesma Idempotency-Key foi usada com um corpo diferenteUse uma chave nova ou envie o mesmo corpo
422Regra de negócio não atendida (expiresIn, etc.)Veja code para detalhe
429Limite de requisições excedidoFaça retry com backoff exponencial
503Provedor temporariamente indisponívelFaça retry — não é problema do seu payload

​
Códigos code que a API emite

codeCategoriaHTTPComo agir
invalid_jsonvalidação400Corpo da requisição não é JSON válido. Confira como você está serializando.
invalid_request_bodyvalidação400Algum campo violou tipo, tamanho ou regra de pelo-menos-um. A message traz o detalhe.
unauthorizedautenticação401Chave ausente, mal formatada, inválida ou revogada.
forbiddenautorização403Conta sem APPROVED para produção.
api_key_scope_forbiddenautorização403A chave não tem permissão para o recurso chamado.
account_suspendedautorização403Conta suspensa. Acesse o app ou entre em contato com o suporte.
live_operations_blockedautorização403Operações em produção temporariamente bloqueadas. Acesse o app ou entre em contato com o suporte.
test_withdrawals_not_supportedautorização403Saques estão disponíveis somente em produção.
withdrawal_readiness_requiredautorização403A conta ainda precisa completar a configuração necessária para saques.
withdrawals_blockedautorização403Saques temporariamente bloqueados para a conta.
idempotency_key_requiredvalidação400O header Idempotency-Key é obrigatório para criar saques pela API.
idempotency_conflictconflito409A mesma Idempotency-Key foi reutilizada com outro corpo.
invalid_expires_inregra (checkout)422expiresIn fora do intervalo 60-86400.
invalid_amountregra (saque)422Valor inválido para o saque solicitado.
insufficient_balanceregra (saque)422Saldo disponível insuficiente para o saque solicitado.
quote_unavailableregra (saque)422Cotação indisponível para o saque solicitado. Tente novamente depois.
checkout_not_foundnot found404O checkoutId não existe ou não pertence à sua conta.
withdrawal_not_foundnot found404O withdrawalId não existe ou não pertence à sua conta.
provider_unavailableprovedor503Provedor de pagamentos temporariamente indisponível. Retry seguro.
rate_limitedlimite429Limite de requisições. Implemente backoff e não repita em loop apertado.

​
Como investigar sem dor

1

Leia o status HTTP

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

Use `code` e `message`

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

Guarde o `requestId`

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

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.