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_amount",
    "message": "amount must be greater than zero",
    "requestId": "req_01HR7PR7W2KCFJ4Q58SFT11X31"
  }
}

Status HTTP mais comuns

HTTP	Quando normalmente aparece
`400`	Payload inválido ou mal formatado
`401`	Chave ausente ou inválida
`403`	Chave sem permissão
`404`	Recurso não encontrado
`409`	Conflito de idempotência
`422`	Regra de negócio não atendida
`429`	Limite de requisições excedido
`500`	Erro inesperado

Códigos frequentes

Código	O que normalmente significa
`invalid_amount`	Valor ausente, zero ou negativo
`invalid_currency`	Moeda não suportada
`invalid_customer`	Dados do comprador inválidos
`checkout_not_found`	Checkout inexistente
`checkout_expired`	Checkout expirado
`unauthorized`	Token inválido
`rate_limited`	Muitas requisições em pouco tempo

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.

Documentação

​Erros

​Formato do erro

​Status HTTP mais comuns

​Códigos frequentes

​Como tratar sem dor