Códigos de erro

Toda resposta de erro segue o formato:

{
  "error": "<tipo curto>",
  "message": "<descrição em português>",
  "request_id": "req_xxx..."
}

O request_id aparece em caso de erro 5xx — guarde pra investigação em suporte.

4xx — erros do cliente

400 Bad Request

Problema na request. Casos comuns:

• Saldo insuficiente (rota de saque):

{
  "error": "Insufficient Balance",
  "message": "Saldo insuficiente pra realizar o saque.",
  "available_cents": 3000,
  "required_cents": 5200
}

401 Unauthorized

Credenciais ausentes ou inválidas.

{
  "error": "Error",
  "message": "Credenciais inválidas."
}

Ação: verifique se os headers client-id e client-secret estão corretos e pertencem a uma conta ativa.

403 Forbidden

Request autenticada, mas merchant não tem permissão pra operação:

• Conta em pending_kyc (ainda não aprovada)
• Conta suspended ou closed

{
  "error": "Error",
  "message": "Conta do merchant não está ativa (status=pending_kyc)."
}

409 Conflict

Idempotency-Key reutilizada pra operação diferente. Veja idempotência.

{
  "error": "Conflict",
  "message": "Idempotency-Key reutilizada pra operação diferente."
}

422 Unprocessable Entity

Schema inválido — campos faltando, tipos errados, valores fora do range:

{
  "error": "Unprocessable Entity",
  "message": "Dados inválidos.",
  "issues": [
    { "path": "amount", "message": "Valor mínimo: 1 centavo" },
    { "path": "payer.document", "message": "CPF/CNPJ inválido" }
  ]
}

429 Too Many Requests

Rate limit excedido. Resposta inclui header Retry-After: <segundos>.

Rate limit padrão: 100 req/min por client-id.

5xx — erros do Moneyfly

500 Internal Server Error

Bug do nosso lado. Inclui request_id pra suporte.

{
  "error": "Internal Server Error",
  "message": "Algo deu errado processando sua requisição.",
  "request_id": "req_abc123xyz..."
}

Ação: tente de novo após ~30 segundos. Se persistir, abra ticket passando o request_id.

502 / 503 / 504

Gateway/upstream com problema temporário. Retry com backoff é a ação correta.

Estratégia de retry

Use idempotency key sempre — assim retries não viram duplicação.

Em caso de dúvida

Antes de abrir suporte:

1. Cheque o request_id nos headers ou body
2. Cheque data/hora exata da request
3. Mande seu client-id (nunca o secret!) e o endpoint chamado

Email: suporte@moneyflybr.com · WhatsApp: clique pra falar