Skip to main content
A API DataBox360 utiliza códigos de status HTTP para informar o resultado das requisições realizadas. Antes de processar uma solicitação, a API realiza validações dos parâmetros enviados, das credenciais de autenticação e das condições necessárias para executar a operação. Quando uma requisição não pode ser concluída, a API retorna um código HTTP correspondente e uma resposta JSON com informações sobre o erro.

​
Visão Geral dos Erros

Os códigos apresentados nesta página correspondem aos erros atualmente documentados pela DataBox360.Outros códigos HTTP poderão ser adicionados conforme a evolução dos serviços e endpoints.

​
400 — Bad Request

Categoria: Erro de validação Ocorre quando a requisição contém parâmetros inválidos, obrigatórios não informados ou dados que não atendem aos critérios de validação da API.

​
Possíveis causas

  • Campos obrigatórios não preenchidos.
  • CPF ou CNPJ em formato inválido.
  • Parâmetros com tipos de dados incorretos.
  • Valores incompatíveis com as regras de validação.
  • Estrutura da requisição diferente da esperada.

​
Como resolver

  1. Verifique os parâmetros obrigatórios do endpoint.
  2. Confira os formatos e tipos de dados enviados.
  3. Identifique os campos indicados na resposta de erro.
  4. Corrija os dados e envie uma nova requisição.

​
Exemplo de resposta

Orientação técnica: utilize as informações retornadas em campo para identificar quais parâmetros precisam ser corrigidos. Não repita automaticamente uma requisição com erro 400 sem corrigir os dados enviados.

​
401 — Unauthorized

Categoria: Erro de autenticação Ocorre quando a API não consegue validar as credenciais utilizadas na requisição.

​
Possíveis causas

  • API Key inválida ou não informada.
  • Token JWT inválido.
  • Token JWT expirado.
  • Cabeçalho Authorization ausente ou incorreto.

​
Como resolver

  1. Verifique se a credencial está correta.
  2. Confirme o formato do cabeçalho Authorization.
  3. Caso o JWT tenha expirado, obtenha um novo token.
  4. Repita a requisição utilizando uma credencial válida.

​
Autenticação na DataBox360

Para obter um token JWT pelo endpoint de autenticação:
Para consumir os endpoints que exigem autenticação JWT:
A API Key e o token JWT são credenciais distintas.Na obtenção do JWT, envie a API Key diretamente no cabeçalho Authorization, sem o prefixo Bearer.Nas requisições autenticadas por JWT, utilize o prefixo Bearer seguido do token recebido.

​
Exemplo de resposta

Orientação técnica: implemente um mecanismo para verificar a validade do token JWT e renová-lo quando necessário. Se a falha estiver relacionada à API Key, verifique a credencial antes de tentar novamente.

​
404 — Not Found

Categoria: Recurso não encontrado Ocorre quando o recurso solicitado não é localizado pela API.

​
Possíveis causas

  • Endpoint inexistente.
  • URL incorreta.
  • Identificador de recurso não encontrado.
  • Recurso solicitado indisponível no endereço informado.

​
Como resolver

  1. Confira a URL da requisição.
  2. Verifique o método HTTP utilizado.
  3. Confirme os identificadores informados.
  4. Consulte a documentação do endpoint correspondente.

​
Exemplo de resposta

Orientação técnica: verifique se o recurso solicitado existe antes de repetir a requisição.
Uma resposta HTTP 404 não significa necessariamente que uma consulta de dados foi executada e não encontrou registros.O tratamento de consultas sem resultados deve seguir as regras específicas do respectivo endpoint.

​
429 — Too Many Requests

Categoria: Limite de requisições Ocorre quando a quantidade de requisições realizadas ultrapassa o limite permitido pela API. O controle de requisições ajuda a preservar a estabilidade e a disponibilidade dos serviços.

​
Possíveis causas

  • Volume excessivo de requisições em um curto período.
  • Múltiplas chamadas simultâneas.
  • Rotinas automatizadas com frequência elevada.
  • Repetições sucessivas de requisições.

​
Como resolver

  1. Interrompa temporariamente as novas requisições.
  2. Aguarde antes de realizar outra tentativa.
  3. Reduza a frequência das chamadas.
  4. Implemente mecanismos de controle de concorrência e retentativas.

​
Exemplo de resposta

​
Boas práticas de integração

Recomendamos implementar:
  • Controle da frequência de chamadas.
  • Filas para processamento de requisições.
  • Retentativas com intervalo progressivo (exponential backoff).
  • Registro de ocorrências para acompanhamento.
Evite repetir imediatamente uma requisição que retornou HTTP 429.Retentativas excessivas podem prolongar o bloqueio ou aumentar a sobrecarga da integração.

​
500 — Internal Server Error

Categoria: Erro interno no servidor Indica que ocorreu uma falha interna durante o processamento da requisição. Diferentemente dos erros de validação, esse código normalmente representa uma condição que não pode ser corrigida apenas com alterações nos parâmetros enviados.

​
Possíveis causas

  • Falha inesperada no processamento.
  • Erro interno da aplicação.
  • Indisponibilidade de uma dependência utilizada pelo serviço.
  • Problemas temporários de infraestrutura.

​
Como resolver

  1. Registre o horário e os detalhes da requisição.
  2. Aguarde alguns instantes antes de tentar novamente.
  3. Verifique se o erro ocorre de forma recorrente.
  4. Caso persista, entre em contato com o suporte técnico da DataBox360.

​
Exemplo de resposta

​
Cuidados com retentativas

Uma resposta HTTP 500 não garante que a operação tenha sido totalmente interrompida antes do processamento. Antes de repetir operações que possam gerar efeitos financeiros ou alterações de estado, verifique se a solicitação anterior foi concluída.
Em operações sujeitas a cobrança, evite retentativas automáticas indiscriminadas.Confirme o resultado do processamento antes de reenviar uma solicitação que possa gerar consumo adicional.

​
Estrutura das Respostas de Erro

Os exemplos documentados utilizam uma estrutura JSON com os seguintes campos:
O campo campo aparece no exemplo de erro de validação HTTP 400 e não necessariamente estará presente nos demais tipos de erro.O nome messagem foi mantido conforme os exemplos atuais da API. Qualquer alteração desse campo deve ser previamente validada com a implementação do serviço.

​
Recomendações para Integração

Para garantir maior estabilidade e facilitar o diagnóstico de problemas, recomendamos as seguintes práticas:

​
1. Verifique sempre o código HTTP

Não utilize apenas o conteúdo da resposta JSON para identificar o resultado de uma requisição. Considere também o código HTTP retornado pelo servidor.

​
2. Implemente tratamento específico por erro

Cada categoria exige uma ação diferente:

​
3. Registre as informações relevantes

Em caso de falha, registre preferencialmente:
  • Endpoint e método HTTP.
  • Código HTTP recebido.
  • Data e hora da ocorrência.
  • Mensagem retornada pela API.
  • Identificador interno da requisição, quando disponível.
Evite registrar API Keys, tokens JWT ou outros dados sensíveis em logs acessíveis.

​
4. Diferencie erros técnicos de resultados de negócio

Uma requisição processada corretamente pode retornar um resultado sem registros disponíveis. Essa situação não deve ser confundida automaticamente com erros de autenticação, validação ou infraestrutura. Consulte a documentação específica de cada produto para interpretar corretamente seus resultados.

​
Precisa de Suporte?

Se o problema persistir após as verificações recomendadas, entre em contato com a equipe de suporte técnico da DataBox360. Ao solicitar atendimento, informe o endpoint utilizado, o código HTTP recebido, a data e hora da ocorrência e uma descrição do comportamento observado. Por segurança, não compartilhe API Keys ou tokens JWT em solicitações de suporte.