Errors
Single error format, HTTP status codes and the most common messages.
Every API error has the same shape:
{ "response": "ERROR", "message": "amount inválido (em reais, ex.: 10.50)" }Some authentication errors also carry code (RATE_LIMITED, ACCOUNT_BLOCKED, KYC_REQUIRED). message is in Portuguese and ready to log; to decide what to do in code, use the HTTP status (and code, when present).
HTTP status
| HTTP | Meaning | Retry? |
|---|---|---|
200 | success | — |
400 | invalid data or business rule (balance, limit, duplicate requestNumber) | no, fix the request |
401 | missing or invalid credentials | no |
403 | account blocked, KYC pending or operation not enabled | no |
404 | transaction or endpoint not found | no |
409 | idempotency key reused with a different request | no |
429 | rate limit | yes, with backoff |
500 / 502 / 503 | temporary failure | yes, with growing backoff — for payouts, always with the same Idempotency-Key |
Common messages
Charges
message | Cause |
|---|---|
requestNumber é obrigatório | field missing or empty |
requestNumber já utilizado | a charge with this requestNumber already exists on the account |
amount inválido (em reais, ex.: 10.50) | zero, negative, non-numeric or more than 2 decimals |
client.name é obrigatório | name shorter than 3 characters |
client.document inválido (CPF ou CNPJ) | check digits do not match |
client.email inválido | malformed e-mail |
callbackUrl inválida | not http(s) or longer than 500 characters |
Split não está liberado nesta conta. Fale com o suporte. (403) | split without Compliance approval |
split.account inválida para split | destination account missing, inactive or your own |
split.percentageSplit deve ser um inteiro entre 1 e 100 | percentage out of range |
Amounts below the platform charge minimum or above its maximum also return 400, with the limit in the message.
Payouts
message | Cause |
|---|---|
Saque pela API não está liberado nesta conta. Ative em Desenvolvedores. (403) | enable API payouts in the dashboard |
typeKey inválido (use CPF, CNPJ, EMAIL, PHONE ou EVP) | unknown key type |
key inválida para o typeKey informado | key does not match its type |
document deve ser o mesmo CPF/CNPJ da chave | CPF/CNPJ key with a different document |
Saque só para a chave CPF/CNPJ do titular da conta… (403) | account not enabled for third-party payouts |
insufficient balance | balance lower than amount + payout fee |
O valor mínimo para saque é … / O valor máximo por saque é … | outside per-payout limits |
Limite diário de saque atingido… | the last 24 h total would exceed the daily limit |
Esta chave de idempotência já foi usada em outro saque (409) | same Idempotency-Key with another amount/key |
Pagamento de PIX copia e cola (QRCODE) ainda não está disponível | typeKey: "QRCODE" is not supported |
Lookup
message | Cause |
|---|---|
Informe requestNumber, idTransaction ou endToEnd | body without any identifier |
Transação não encontrada (404) | not found on your account |
Endpoint não encontrado (404) | wrong path (check /api/v1/gateway/…) |