Codigos de Erro

Codigos de Status HTTP

Codigo	Status	Descricao
200	OK	Requisicao processada com sucesso.
201	Created	Recurso criado com sucesso.
400	Bad Request	Dados da requisicao invalidos (campos faltando, formato incorreto).
401	Unauthorized	Credenciais ausentes, invalidas ou token expirado.
403	Forbidden	Sem permissao para acessar o recurso ou feature nao habilitada no plano.
404	Not Found	Recurso nao encontrado ou nao pertence a sua empresa.
429	Too Many Requests	Limite de taxa excedido. Aguarde e tente novamente.
500	Internal Server Error	Erro interno do servidor. Contate o suporte se persistir.

Formato da Resposta de Erro

Todas as respostas de erro seguem o mesmo formato:

{
  "statusCode": 400,
  "message": "VALIDATION_ERROR",
  "friendlyMessage": "O campo 'name' e obrigatorio."
}

Campo	Tipo	Descricao
statusCode	number	Codigo HTTP do erro.
message	string	Codigo interno do erro (constante, em ingles). Util para tratamento programatico.
friendlyMessage	string	Mensagem legivel em portugues. Pode ser exibida ao usuario final.

Alguns erros de validacao podem incluir detalhes adicionais:

{
  "statusCode": 400,
  "message": "VALIDATION_ERROR",
  "friendlyMessage": "Dados invalidos. Verifique os campos e tente novamente.",
  "errors": [
    {
      "field": "documentNumber",
      "message": "CPF/CNPJ invalido."
    },
    {
      "field": "originalAmount",
      "message": "O valor deve ser maior que zero."
    }
  ]
}

Erros Comuns e Solucoes

401 — Unauthorized

Mensagem	Causa	Solucao
INVALID_CREDENTIALS	API Key ou Secret incorretos	Verifique as credenciais. Regenere se necessario.
TOKEN_EXPIRED	O accessToken expirou	Chame POST /external/v1/auth/refresh-token para renovar.
TOKEN_INVALID	Token mal formado ou revogado	Autentique novamente com POST /external/v1/auth.
MISSING_AUTH_HEADER	Header Authorization ausente	Inclua Authorization: Bearer {token} na requisicao.
MISSING_COMPANY_TOKEN	Header x-company-token ausente	Inclua x-company-token: {companyToken} na requisicao.

400 — Bad Request

Mensagem	Causa	Solucao
VALIDATION_ERROR	Campos obrigatorios faltando ou formato invalido	Verifique o body da requisicao conforme a documentacao do endpoint.
INVALID_ENUM_VALUE	Valor nao permitido para campo enum	Consulte os valores aceitos na documentacao do recurso.
INVALID_DATE_FORMAT	Data em formato incorreto	Use o formato ISO 8601: YYYY-MM-DD ou YYYY-MM-DDTHH:mm:ssZ.
DUPLICATE_ENTRY	Registro duplicado (ex: mesmo documentNumber)	Verifique se o registro ja existe antes de criar.

403 — Forbidden

Mensagem	Causa	Solucao
FEATURE_NOT_ENABLED	Feature nao habilitada no plano da empresa	Contate o administrador para habilitar a feature no plano.
INSUFFICIENT_PERMISSIONS	API Key sem permissao para este recurso	Verifique as permissoes da chave ou gere uma nova com escopo adequado.

404 — Not Found

Mensagem	Causa	Solucao
RESOURCE_NOT_FOUND	ID inexistente ou recurso inativo	Verifique se o ID esta correto e se o recurso nao foi inativado.
ROUTE_NOT_FOUND	Endpoint inexistente	Verifique a URL e a versao da API (/v1).

429 — Too Many Requests

Mensagem	Causa	Solucao
RATE_LIMIT_EXCEEDED	Mais de 100 requisicoes por minuto	Implemente exponential backoff. Veja Rate Limits.

500 — Internal Server Error

Mensagem	Causa	Solucao
INTERNAL_ERROR	Erro inesperado no servidor	Tente novamente apos alguns segundos. Se persistir, abra um chamado no suporte com o requestId (quando disponivel).

Boas Praticas de Tratamento de Erros

1. Sempre verifique o statusCode antes de processar a resposta
2. Trate 401 com renovacao automatica de token e retry da requisicao original
3. Trate 429 com exponential backoff (veja Rate Limits)
4. Registre logs com statusCode, message e o body enviado para facilitar debug
5. Nao exiba message ao usuario final — use friendlyMessage que ja esta em portugues
6. Em caso de 500, aguarde pelo menos 5 segundos antes de tentar novamente