Seção 12
Tratamento de Erros
Os erros trazem um corpo JSON com o campo detail:
{ "detail": "Merchant 77 nao esta APPROVED" }
Nos erros de validação (422), o detail pode ser uma lista que aponta o campo com problema:
{
"detail": [
{ "loc": ["body", "amount_cents"], "msg": "Input should be greater than 0", "type": "greater_than" }
]
}
| Status | Significado | O que fazer |
|---|---|---|
400 | Requisição malformada (ex.: Idempotency-Key inválida) | Corrija o cabeçalho ou o corpo |
401 | Token ausente, inválido ou substituído | Confira o token; gere um novo se preciso |
403 | Sem permissão para a operação | Verifique o usuário/token |
404 | Recurso não encontrado (ou de outro estabelecimento) | Confira o id |
409 | Conflito: estabelecimento ainda não aprovado, cobrança que já não pode ser alterada, ou idempotência em andamento | Veja a mensagem; aguarde ou conclua o cadastro |
422 | Dados inválidos, ou recusa do processador de pagamentos | Leia o detail |
429 | Muitas requisições (páginas públicas) | Espere e tente de novo |
502 | O processador de pagamentos está indisponível | Tente de novo com espera, usando Idempotency-Key |
Problemas comuns
| Sintoma | Causa provável |
|---|---|
409 ao criar cobrança | O estabelecimento ainda não está Aprovado (cadastro ou KYC pendente) |
401 de repente | O token foi substituído por um novo |
| Erro ao criar boleto | Falta boleto/boleto_config, ou o cliente não tem o endereço completo (rua, número, bairro, cidade, UF e CEP) |
409 ao alterar cobrança | A cobrança já não está PENDING, ou há uma tentativa em andamento |
| Aviso não chega | Endereço não é https público, resposta fora de 2xx ou acima de 10 s. Veja GET /webhook-deliveries |
| Assinatura não confere | Validou sobre o JSON reserializado em vez do corpo bruto, ou usou o segredo antigo |