Erros
Formato único de erro, códigos HTTP e mensagens mais comuns.
Todo erro da API tem o mesmo formato:
{ "response": "ERROR", "message": "amount inválido (em reais, ex.: 10.50)" }Alguns erros de autenticação trazem também code (RATE_LIMITED, ACCOUNT_BLOCKED, KYC_REQUIRED). message é em português e pronta para log; para decidir o que fazer no código, use o status HTTP (e o code, quando houver).
Status HTTP
| HTTP | Significado | Repetir? |
|---|---|---|
200 | sucesso | — |
400 | dados inválidos ou regra de negócio (saldo, limite, requestNumber repetido) | não, corrija o pedido |
401 | credenciais ausentes ou inválidas | não |
403 | conta bloqueada, KYC pendente ou operação não liberada | não |
404 | transação ou endpoint não encontrado | não |
409 | chave de idempotência reutilizada com outro pedido | não |
429 | limite de requisições | sim, com espera |
500 / 502 / 503 | falha temporária | sim, com espera crescente — em saques, sempre com a mesma Idempotency-Key |
Mensagens comuns
Cobranças
message | Causa |
|---|---|
requestNumber é obrigatório | campo ausente ou vazio |
requestNumber já utilizado | já existe uma cobrança com esse requestNumber na conta |
amount inválido (em reais, ex.: 10.50) | zero, negativo, não numérico ou com mais de 2 casas |
client.name é obrigatório | nome com menos de 3 caracteres |
client.document inválido (CPF ou CNPJ) | dígitos verificadores não conferem |
client.email inválido | e-mail mal formatado |
callbackUrl inválida | não é http(s) ou passa de 500 caracteres |
Split não está liberado nesta conta. Fale com o suporte. (403) | split sem liberação do Compliance |
split.account inválida para split | conta de destino inexistente, inativa ou a própria conta |
split.percentageSplit deve ser um inteiro entre 1 e 100 | percentual fora da faixa |
Valores abaixo do mínimo ou acima do máximo de cobrança da plataforma também voltam como 400, com o limite na mensagem.
Saques
message | Causa |
|---|---|
Saque pela API não está liberado nesta conta. Ative em Desenvolvedores. (403) | ligue o saque pela API no painel |
typeKey inválido (use CPF, CNPJ, EMAIL, PHONE ou EVP) | tipo de chave desconhecido |
key inválida para o typeKey informado | chave não corresponde ao tipo |
document deve ser o mesmo CPF/CNPJ da chave | chave CPF/CNPJ com document diferente |
Saque só para a chave CPF/CNPJ do titular da conta… (403) | conta sem liberação para pagar terceiros |
insufficient balance | saldo menor que valor + tarifa de saque |
O valor mínimo para saque é … / O valor máximo por saque é … | fora dos limites por saque |
Limite diário de saque atingido… | soma das últimas 24 h passaria do limite diário |
Esta chave de idempotência já foi usada em outro saque (409) | mesma Idempotency-Key com outro valor/chave |
Pagamento de PIX copia e cola (QRCODE) ainda não está disponível | typeKey: "QRCODE" não é suportado |
Consulta
message | Causa |
|---|---|
Informe requestNumber, idTransaction ou endToEnd | corpo sem nenhum identificador |
Transação não encontrada (404) | não existe na sua conta |
Endpoint não encontrado (404) | caminho errado (confira /api/v1/gateway/…) |