Skip to main content
Este catálogo reúne as respostas de erro de cada rota da API. As mensagens estão exatamente como a API as devolve: algumas em português, outras em inglês, às vezes na mesma rota. Use a página para montar o tratamento de erros, configurar alertas e orientar o suporte. Para o formato geral das respostas e a regra de quando repetir uma requisição, veja Erros e como tratar.

Como ler as tabelas

A API usa três formatos de corpo:
Para o desenvolvedor: decida o fluxo pelo código HTTP e, quando existir, pelo code ou pelo error dos dois últimos formatos. Use o texto de message só para log e diagnóstico: ele mistura idiomas e pode mudar.

Erros comuns a todas as rotas

Cobranças

POST /v1/charges

Recusas chegam com 201, status refused ou failed e o motivo em reason. Também sai o webhook charge.refused ou charge.failed. Quando a análise antifraude manda a cobrança para revisão manual, ela fica in_analysis com reason antifraud_manual_review. Não é recusa: aguarde o desfecho. Erros de Apple Pay nesta rota, no formato { code, message }:

GET /v1/charges e GET /v1/charges/{id}

GET /v1/charges/{id} com um id que não existe responde hoje 200 com corpo vazio, sem 404. Trate corpo vazio como “cobrança não encontrada”. Confira também se a chave é do mesmo ambiente da cobrança: a chave de teste só enxerga cobranças de teste.

POST /v1/refunds

POST /v1/charges/{id}/resend-webhook

Apple Pay (domínios e sessão)

Erros de negócio no formato { code, message }. Erros de validação de campo vêm no formato padrão, com message em lista, e o 403 de permissão traz Acesso negado.

Saldos e meios de pagamento

Saques

Não existe saque no Modo Teste. Os erros de regra vêm em inglês.

POST /v1/payout-requests (própria conta)

POST /v1/submerchants/{merchantId}/payout-requests (subconta)

GET /v1/payout-requests

Clientes

Cartões

3D Secure

As rotas abaixo usam a chave pública (pk_).

Planos de assinatura

Todas as rotas de planos respondem 403 com Acesso negado para chaves de Desenvolvedor e Financeiro. O Visualizador só acessa as consultas (GET).

Assinaturas

Todas as rotas de assinaturas respondem 403 com Acesso negado para chaves de Desenvolvedor e Financeiro. O Visualizador só acessa as consultas (GET).

Connect

As rotas do Connect respondem 403 com Fast Connect not enabled. quando o módulo não está habilitado na conta master.

Subcontas

Documentos e representantes

Em POST /v1/document-uploads, os erros de arquivo vêm no formato { "error": "<CÓDIGO>", "message": "...", "details": { ... } }, sem statusCode. Os erros do token (401 e 403) vêm no formato padrão.

Taxas e dados da subconta

Endpoints de webhook

Veja também

Erros e como tratar

Formato das respostas e quando repetir.

Mapa da API

Todas as rotas e sua autenticação.

Status de cobrança

Recusas, bloqueios e disputas.

Credenciais e ambientes

Permissões da chave e autenticação.