Saques e saldo
Erros de saque
Todos os códigos que as rotas de saque podem devolver, o que cada um significa e se vale repetir a chamada.
As rotas de saque respondem erros em Problem Details. O código estável está em type; title é genérico por operação e detail é texto livre para pessoas.
{
"type": "withdrawal.insufficient_balance",
"title": "Withdrawal creation failed",
"status": 422,
"detail": "Insufficient balance."
}Erros de formato do JSON têm outra cara: type é uma URL e os detalhes estão em errors.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"$.pixKeyType": ["The JSON value could not be converted to PixKeyType."]
},
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}Criação
| HTTP | type | Causa | Repetir? |
|---|---|---|---|
400 | URL + errors | JSON malformado, campo obrigatório ausente ou pixKeyType desconhecido (por exemplo EVP). | Não. Corrija o corpo. |
400 | idempotency_key_required | Sem Idempotency-Key no cabeçalho nem no corpo. | Não. |
400 | withdrawal.validation_failed | Valor abaixo de 100 (R$ 1,00) ou com casas decimais, moeda diferente de BRL, chave de idempotência fora de 10 a 200 caracteres, chave Pix ou documento inválidos. O detail lista cada problema. | Não. |
409 | withdrawal.idempotency_conflict | A chave de idempotência já foi usada com outro valor, chave Pix ou conta. | Não. Use outra chave para outro pedido. |
422 | withdrawal.insufficient_balance | O saldo disponível para saque é menor que o valor. | Sim, quando houver saldo. A mesma chave pode ser reutilizada. |
422 | withdrawal.invalid_account | accountId não pertence à sua conta. | Confira o accountId. Se estiver certo e o erro persistir, fale com a equipe de integração. |
422 | withdrawal.provider_account_not_configured | A conta de saque não está configurada no cadastro. | Fale com a equipe de integração. |
422 | withdrawal.destination_not_configured | Não há chave Pix de destino cadastrada. | Fale com a equipe de integração. |
422 | withdrawal.destination_not_owned | A chave Pix, o tipo ou o documento enviados não são os do cadastro. | Não. Use a chave cadastrada. |
422 | withdrawal.source_is_master_account | A conta de origem cadastrada não pode ser usada para saque. | Fale com a equipe de integração. |
422 | withdrawal.amount_limit_exceeded | O valor passa do limite por saque. | Não, com o mesmo valor. |
422 | withdrawal.daily_count_limit_exceeded | Limite diário de quantidade atingido. | No dia seguinte (UTC). |
422 | withdrawal.daily_amount_limit_exceeded | Limite diário de valor atingido. | No dia seguinte (UTC). |
500 | withdrawal.internal_error ou outro | Falha inesperada. | Sim, com a mesma chave e o mesmo corpo. |
Consulta, listagem e cancelamento
| HTTP | type | Rota | Causa |
|---|---|---|---|
400 | withdrawal.invalid_status | Listagem | status desconhecido. |
400 | invalid_page_size | Listagem | pageSize maior que 100. |
400 | withdrawal.validation | Listagem | page ou pageSize menor que 1. |
404 | withdrawal.not_found | Consulta, cancelamento | Saque inexistente ou de outra conta. |
404 | sem corpo | Consulta, cancelamento | O id não é um UUID. |
409 | withdrawal.cannot_cancel | Cancelamento | O saque já foi aprovado ou chegou a um estado final. |
500 | withdrawal.retrieval_error, withdrawal.list_error, withdrawal.internal_error | Todas | Falha inesperada. Repita com espera crescente. |
Erros comuns a todas as rotas de saque
| HTTP | Corpo | Causa |
|---|---|---|
401 | {"message":"Unauthorized"} | Cabeçalho Authorization ausente. |
403 | {"message":"Forbidden"} | A chave não tem permissão de saque. |
403 | type: ip_not_allowed | O IP de origem não está na lista permitida da conta. |
429 | sem corpo | Mais de 60 requisições por minuto. Espere e repita com espera crescente. |
503 | type: ip_allowlist_unavailable | A lista de IPs não pôde ser verificada. Repita em alguns segundos. |
500 | {"message":"Internal Server Error"} | Chave de API inválida, expirada ou revogada. Veja Autenticação. |
Repetição segura
Na criação, repita sempre com a mesma Idempotency-Key e o mesmo corpo. Assim, se o primeiro pedido tiver sido registrado antes da falha, a repetição devolve o mesmo saque em vez de criar outro. Nunca gere uma chave nova para "tentar de novo" um saque cujo resultado você não conhece: consulte a listagem antes.