Rotas sob /v1/* retornam erros em JSON padronizado. Rotas de dashboard e autenticação podem usar formato NestJS clássico (statusCode, message).
Envelope de erro (API pública)
{
"success": false,
"message": "Mensagem legível para integração",
"error": {
"code": "Bad Request",
"statusCode": 400
},
"requestId": "req_7f3a2b1c"
}
| Campo | Descrição |
|---|
message | Texto principal (pode repetir detalhe de validação) |
error.code | Nome da exceção HTTP (ex.: Bad Request, Unauthorized, Forbidden, Not Found, Conflict) |
error.statusCode | Código HTTP numérico |
requestId | Identificador para suporte |
Não existe enum fixa BAD_REQUEST no campo code. Use error.statusCode e message na lógica do integrador.
Status HTTP frequentes
| Status | Situação típica |
|---|
400 | Body inválido, regra de negócio (saldo, trilho, limites) |
401 | Chave ausente, revogada ou inválida |
403 | Chave sem permissão na rota; trilho indisponível; conta suspensa |
404 | Recurso não encontrado ou de outra conta |
409 | Conflito de unicidade (ex.: externalReference duplicado) |
429 | Rate limit excedido |
500 | Erro interno (retente com backoff; abra ticket com requestId) |
Códigos de domínio (trilho)
Respostas 403 ou 409 podem incluir mensagens relacionadas a:
| Código lógico | Significado |
|---|
RAIL_UNAVAILABLE | Trilho não habilitado na conta |
RAIL_ACCESS_REVOKED | Acesso ao trilho revogado |
RAIL_OPERATION_NOT_ALLOWED | Operação não permitida neste trilho |
RAIL_REQUIRED | Operação exige trilho específico |
Validação de body
Campos inválidos retornam 400 com mensagem agregada. Exemplos:
amount abaixo do mínimo da operaçãodescription com menos de 3 caracteressplitUser sem splitTax (ou vice-versa)pixKey ausente quando não há pixCopyPaste
Prisma e conflitos
Violação de unicidade no banco (P2002) mapeia para 409 Conflict.
Rate limiting
429 com corpo simplificado. Veja Rate limiting.
Boas práticas
Registre sempre requestId nos logs do seu servidor ao tratar erros 5xx.
Não interprete mensagens em português como API estável: prefira statusCode e campos estruturados em data nas respostas de sucesso.
Em webhooks inbound para seu servidor, valide assinatura antes de processar. Erros de parsing devem retornar 4xx apenas quando o payload for inválido; duplicatas devem retornar 200.
