Erros e diagnóstico
Leia o código, corrija a chamada e use o requestId para investigar.
Formato de erro
Erros retornam error, message e requestId. Erros de validação também incluem details com caminho e mensagem de cada campo. Guarde o requestId ao falar com o suporte.
{"error":"validation_error","message":"Dados da requisição inválidos.","requestId":"<id>","details":[{"path":"payer.taxId","message":"CPF ou CNPJ inválido."}]}Códigos frequentes
400 validation_error: revise campos e tipos. 400 idempotency_key_required ou invalid_idempotency_key: envie uma chave válida. 401 invalid_api_key: verifique Bearer, validade, revogação e IP permitido. 403 insufficient_scope ou organization_not_active: revise permissão e organização.
404 payment_not_found: confirme UUID e organização. 409 idempotency_conflict ou request_in_progress: não reutilize chave para operação diferente. 429: reduza frequência. 503 provider_unavailable: provedor de produção não habilitado.
Investigar uma falha
Confirme ambiente, rota, escopos, formato do corpo e Idempotency-Key. Para webhook ausente, confira evento selecionado, ambiente, URL HTTPS e histórico de entregas. Anote requestId, rota e horário; nunca envie o token completo em um chamado.