Envelope de erro
As rotas /developer/* respondem erros no formato abaixo, com um code estável para o seu código tratar e o request_id (também no header X-Request-Id) para o suporte localizar a chamada.
{
"success": false,
"message": "Esta chave não tem o escopo 'payments:read'.",
"error": {
"code": "insufficient_scope",
"message": "Esta chave não tem o escopo 'payments:read'.",
"details": {
"required_scope": "payments:read"
},
"request_id": "req_01J9..."
},
"request_id": "req_01J9..."
}
| HTTP | code | Quando |
|---|---|---|
| 400 | bad_request | Requisição malformada |
| 401 | invalid_api_key | Chave ausente ou inválida |
| 401 | api_key_revoked / api_key_expired | Chave revogada ou expirada |
| 403 | insufficient_scope | A chave não tem o escopo da rota |
| 403 | account_inactive | Conta suspensa ou inativa |
| 404 | payment_not_found, withdrawal_not_found, not_found | Recurso inexistente neste ambiente |
| 409 | idempotency_key_in_progress | Mesma Idempotency-Key ainda em processamento |
| 422 | idempotency_key_reused | Mesma Idempotency-Key com rota ou corpo diferentes |
| 422 | validation_error | Campos inválidos (detalhes em errors) |
| 429 | rate_limited | Limite da chave atingido |
| 5xx | internal_error | Erro nosso: tente de novo com a mesma Idempotency-Key |
Erros na criação de cobranças
As rotas POST /payments/{metodo} mantêm o formato antigo por compatibilidade: o código estável vem em error_code (compare sem diferenciar maiúsculas), o texto em message, os erros por campo em errors e o request_id no corpo. O campo error, quando vem, pode ser um texto.
{
"success": false,
"message": "Erro de validação: O número de telefone é obrigatório.",
"errors": {
"phone": [
"O número de telefone é obrigatório."
]
},
"error_code": "validation_error",
"request_id": "6f1c..."
}
| HTTP | error_code | Quando |
|---|---|---|
| 401 | invalid_api_key, api_key_revoked, api_key_expired | Chave ausente, inválida, revogada ou expirada |
| 403 | insufficient_scope | Chave sem payments:write (aqui o erro vem em error.code) |
| 403 | account_pending_approval | Conta ainda não aprovada pela equipe |
| 403 | account_inactive | Conta suspensa ou bloqueada |
| 422 | validation_error | Campos inválidos (veja errors); order_id repetido também cai aqui |
| 422 | amount_out_of_limits | Valor fora dos limites da plataforma |
| 422 | idempotency_key_reused | Mesma Idempotency-Key com corpo diferente |
| 429 | rate_limited | Mais de 30 criações por minuto do mesmo IP |
Idempotência
Envie Idempotency-Key (até 255 caracteres) nas criações, estornos e simulações. Mesma chave + mesma rota + mesmo corpo em até 24 h devolve a resposta original com o header Idempotent-Replayed: true, sem executar de novo. Mesma chave com rota ou corpo diferente: 422 idempotency_key_reused. Ainda processando: 409 idempotency_key_in_progress. Respostas 5xx e 429 não são guardadas, então é seguro tentar de novo. As chaves valem por ambiente: a mesma Idempotency-Key usada no sandbox não devolve a resposta de teste numa chamada de produção.
Limites de requisição
A API pública (/developer/*) limita por chave: 120 requisições por minuto por padrão. Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining; no limite, 429 com Retry-After em segundos. A criação de pagamentos tem limite próprio de 30 por minuto por IP.
Versão
Os webhooks levam api_version. Mudanças incompatíveis ganham nova versão e são anunciadas no changelog.