Erros

Toda resposta de erro segue o envelope canônico:

{
  "error": {
    "type": "...",
    "code": "...",
    "message": "...",
    "param": "field-name",
    "request_id": "evt_...",
    "retryable": false,
    "vendor": "pagarme"
  }
}

request_id é sempre retornado também via header x-request-id para correlação com nossos logs.

Códigos por tipo

invalid_request

code	http	retryable	descrição
validation_error	400	false	Body / query não bate com o schema
idempotency_conflict	409	false	Idempotency-Key reutilizada com body diferente
validation_error	404	false	Recurso não encontrado (charge, refund, customer)
validation_error	409	false	Estado inválido (refund de charge não succeeded etc)
test_mode_unavailable	422	false	Chave sk_test_ pediu algo sem sandbox: método sem sandbox do adquirente configurado, ou operação que só existe com dinheiro real (saque, antecipação, cripto, recebedor, assinatura, link de pagamento). Nada foi cobrado — o modo de teste nunca cai para produção

authentication

code	http	retryable	descrição
unauthorized	401	false	API key faltando, mal-formada, não reconhecida ou revogada

rate_limit

code	http	retryable	descrição
rate_limited	429	true	Limite por merchant excedido — reduza o ritmo

vendor

code	http	retryable	descrição
vendor_unavailable	503	true	Adquirente fora do ar / sem capacidade para o método
card_declined	402	false	Adquirente recusou cobrança no cartão

compliance

code	http	retryable	descrição
kyc_required	403	false	Merchant precisa completar onboarding

api

code	http	retryable	descrição
internal_error	500	false	Erro interno — abra ticket com request_id

Boas práticas

• Sempre logar request_id quando uma requisição falhar; é a chave para suporte resolver o caso.
• Respeitar retryable — se for false, retentar não vai ajudar; corrija o input.
• Backoff exponencial em 429 e em 503 vendor_unavailable. Comece em 1 s, dobre a cada tentativa, até 5 min.
• vendor_ref sai populado no objeto Charge mesmo em casos de falha; útil para reconciliar com extrato do adquirente.