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.

OAuth 2.0

Rotas em /oauth/* e /.well-known/oauth-authorization-server seguem RFC 6749 — resposta JSON sem envelope { success, message, data }.

`error`	Situação típica
`invalid_request`	Parâmetro ausente ou malformado
`invalid_client`	`client_id` desconhecido ou secret incorreto
`invalid_grant`	Code expirado, PKCE inválido ou refresh token revogado
`invalid_scope`	Scope não permitido na aplicação
`unsupported_grant_type`	`grant_type` não suportado
`access_denied`	Usuário negou consent (redirect, não JSON)

Na API /v1/* com bearer OAuth:

HTTP	`error`	Situação
401	`invalid_token`	Token expirado ou revogado
403	`insufficient_scope`	Scope do token insuficiente para a rota

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

OAuth 2.0

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

​OAuth 2.0

​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

OAuth 2.0

Boas práticas