Realfy Realfy Docs Painel

Recursos

Códigos de erro

Catálogo completo dos códigos que a API pode retornar, com HTTP status, o que aconteceu e o que fazer.

Formato

Toda resposta de erro segue esse formato:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Um ou mais campos falharam na validação.",
    "details": [
      { "field": "amount", "error": "deve ser maior que 0" }
    ],
    "requestId": "abc-123-def"
  }
}
Use o requestId ao reportar erros pro suporte — a gente acha exatamente o que aconteceu nos logs.

Autenticação & Acesso

Erros de credenciais e permissões.

CodeHTTPO que aconteceuO que fazer
AUTH_REQUIRED 401 Headers X-Api-Key e/ou X-Api-Secret ausentes. Confira os headers da request.
INVALID_CREDENTIALS 401 API key inválida, secret errado, ou key inativa. Gere um novo par no painel.
COMPANY_SUSPENDED 403 Conta da sua empresa foi suspensa pela equipe. Contate o suporte.
IP_NOT_ALLOWED 403 IP fora da allowlist configurada na API key (cash-out only). Adicione o IP no painel da key.

Validação

Campos do body inválidos ou mal-formatados.

CodeHTTPO que aconteceuO que fazer
VALIDATION_ERROR 400 Um ou mais campos do body falharam na validação. Veja error.details[] pra saber qual campo.
INVALID_AMOUNT 400 Valor monetário inválido ou abaixo do mínimo. Verifique formato (decimal, máx 2 casas).
INVALID_DOCUMENT 400 CPF (11 dígitos) ou CNPJ (14) inválido. Confira o documento do cliente.
PIX_KEY_NOT_FOUND 422 A chave PIX informada não existe no DICT do BACEN. Confirme a chave com o destinatário.
RECIPIENT_DOCUMENT_REQUIRED 400 Pra chave EVP/email/telefone, o CPF/CNPJ do destinatário é obrigatório. Inclua customer.document.

Regras de negócio

Operação válida mas viola limites/saldo.

CodeHTTPO que aconteceuO que fazer
INSUFFICIENT_BALANCE 400 Saldo insuficiente pra cobrir o valor + taxa. Recarregue a conta antes de tentar de novo.
WITHDRAWAL_LIMIT_EXCEEDED 400 Valor acima do limite máximo por transação configurado. Reduza o valor ou solicite aumento.
DEPOSIT_LIMIT_EXCEEDED 400 Idem pra cobrança. Reduza o valor ou solicite aumento.
DUPLICATE_REFERENCE 409 A reference já foi usada nesta conta. Gere uma reference única por operação.

Idempotency

Reuso indevido de Idempotency-Key.

CodeHTTPO que aconteceuO que fazer
IDEMPOTENCY_KEY_CONFLICT 409 A mesma Idempotency-Key foi reusada com body diferente. Gere uma key nova OU envie o mesmo body do request original.
IDEMPOTENCY_KEY_INVALID 409 Idempotency-Key > 255 caracteres. Use uma string mais curta (UUID v4 cabe).

Rate limits

Limite de requests excedido.

CodeHTTPO que aconteceuO que fazer
RATE_LIMIT_EXCEEDED 429 Excedeu o limite de requests/min da sua API key. Aguarde Retry-After segundos e tente de novo. Considere backoff exponencial.

Provider / BaaS

Falhas do lado do provedor de pagamento.

CodeHTTPO que aconteceuO que fazer
PROVIDER_UNAVAILABLE 503 Provedor BaaS está fora do ar temporariamente. Retry com backoff em 30-60s.
PROVIDER_NOT_CONFIGURED 503 Integração mal configurada do nosso lado. Contate o suporte imediatamente.
OPERATION_FAILED 502 Operação falhou no provedor sem motivo claro. Retry. Se persistir, contate suporte.
OPERATION_REJECTED 422 Provedor rejeitou a operação (chave inválida, conta bloqueada, etc). Veja a mensagem específica.