Erros e códigos HTTP

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ção
description com menos de 3 caracteres
splitUser 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.

Começar

Integração

Tutoriais

Ajuda

Erros e códigos HTTP

Envelope de erro (API pública)

Status HTTP frequentes

Códigos de domínio (trilho)

Validação de body

Prisma e conflitos

Rate limiting

Boas práticas

​Envelope de erro (API pública)

​Status HTTP frequentes

​Códigos de domínio (trilho)

​Validação de body

​Prisma e conflitos

​Rate limiting

​Boas práticas

Envelope de erro (API pública)

Status HTTP frequentes

Códigos de domínio (trilho)

Validação de body

Prisma e conflitos

Rate limiting

Boas práticas