Erros não usam o envelope de sucesso. A forma é sempre esta:
"message": "Invalid request payload"
O campo error repete o status HTTP; message é uma frase curta, em inglês,
segura para registrar em log. Detalhe interno nunca vaza para a mensagem.
| Status |
Quando acontece |
O que fazer |
| 400 |
Payload inválido, campo obrigatório ausente, chave Pix fora do formato, valor fora dos limites da conta |
Corrija a requisição. Repetir igual não adianta. |
| 401 |
x-api-key/x-token ausente ou inválido |
Confira as credenciais e o ambiente (sandbox × produção). |
| 403 |
Conta aguardando aprovação, lojista pausado pelo operador, escopo insuficiente |
Ação do operador ou chave com outro escopo. |
| 404 |
Recurso não encontrado (ou não é seu) |
Confira o magic_id. |
| 409 |
Transição de status inválida, ou idempotency-key ainda em processamento |
Aguarde e consulte o estado atual antes de repetir. |
| 410 |
Recurso expirou e não está mais disponível |
Crie um novo. |
| 422 |
Saldo insuficiente, limite diário atingido, idempotency-key reusado com outro payload |
Trate como regra de negócio, não como bug de payload. |
| 429 |
Limite de requisições estourado |
Espere e repita com backoff. |
| 500 |
Falha interna |
Pode repetir com o mesmo idempotency-key — respostas 5xx não são guardadas. |
| 501 |
Recurso existe mas está desativado (hoje: estorno pela API) |
Fale com o suporte. |
| Mensagem |
Status |
Missing x-api-key or x-token header |
401 |
Invalid API credentials |
401 |
Rate limit exceeded for this IP |
429 |
Rate limit exceeded for this merchant |
429 |
Your account is awaiting operator approval |
403 |
| Mensagem |
Status |
idempotency-key header is required |
400 |
idempotency-key already used with a different payload |
422 |
A request with this idempotency-key is still being processed |
409 |
| Mensagem |
Status |
Invalid request payload |
400 |
unsupported payment_method "…" |
400 |
amount is below the minimum charge of R$ … |
400 |
amount is above the maximum charge of R$ … |
400 |
daily charge limit of R$ … reached (R$ … already issued today) |
422 |
Refunds are not available through the API: … |
501 |
As mensagens de erro de split (parceria não autorizada, amount e
percentage juntos, soma acima do valor…) estão no
guia de split.
| Mensagem |
Status |
unsupported transfer_method "…" |
400 |
cpf key must be 11 digits (e as demais por tipo de chave) |
400 |
requester.name is required |
400 |
Insufficient available balance |
422 |
merchant is paused by the operator; new withdrawals are disabled |
403 |
Os formatos de chave estão em
Formatos de chave Pix.
| Mensagem |
Status |
Resource not found |
404 |
Invalid status transition |
409 |
Resource is no longer available |
410 |
Internal server error |
500 |
Route not found |
404 |
Method not allowed |
405 |
- 4xx (menos 409 e 429) — erro seu. Não repita a mesma requisição; corrija.
- 409 e 429 — repita com backoff, depois de consultar o estado atual.
- 5xx — repita com backoff e o mesmo
idempotency-key. A operação não
foi registrada.
- Nunca derive lógica de negócio do texto da
message: use o error e o
status do recurso. As mensagens podem ser reescritas.
