Table of Contents

Explicação dos códigos de erro das APIs de reconhecimento em nuvem

Formato da resposta

Todas as respostas da API seguem um formato JSON unificado. Segue um exemplo:

{

  "statusCode": 422,

  "reuslt": "The image or meta exceeds its maximum permitted size",

  "timestamp": 1514736000000,

  "appKey": "test_app_key"

}
Campo Tipo Descrição
statusCode integer Código de status do negócio, 0 indica sucesso, diferente de 0 indica erro
result string Conteúdo retornado. Quando o statusCode é 0, retorna a estrutura do objeto da imagem-alvo, caso contrário retorna uma mensagem de erro
timestamp long Carimbo de data/hora Unix do servidor (em milissegundos)
Importante

Somente quando statusCode == 0, o result inclui o conteúdo da resposta. Em outros estados, result retorna uma mensagem de erro.

Classificação dos códigos de erro

Explicação dos códigos de status HTTP

Código de Status HTTP Descrição
200 Requisição bem-sucedida (pode conter erros de negócio)
400 Erro de parâmetro na requisição
401 Falha na autenticação da APIKey
403 Permissões insuficientes ou recurso com acesso proibido
404 Caminho (Path) da URL da requisição não existe
500 Erro interno do servidor
501 Exceção capturada na aplicação, possivelmente erro de dados
502 Servidor indisponível, contate o suporte
Nota

Erros de negócio normalmente são retornados via resposta HTTP 200, identificados no campo statusCode.

Tabela resumida dos códigos de status de negócio

Status Code Mensagem
0 ok
1 invalid appId (appKey)
2 invalid signature
3 invalid date
4 appId (appKey) not exist
6 invalid token
6 invalid appkey token
7 non-sdk client for dau databases
8 Dau databases are not compatible with sense-4.6+ any more.
404 Target not found
414 Parameter required not exists or not correct
422 The image or meta exceeds its maximum permitted size
417 fail to add image
419 Cannot update target in database because similar target exists.
420 Target delete failed
424 Target enable error
403 Target already exists
426 Judge exceeds maxium candidates
427 Image not correct

Cenários comuns de erro

Sem resposta devido a tempo limite

  • Request Timeout: Rede lenta, recomenda-se verificar o ambiente de rede do cliente.

Erros relacionados à autenticação

  • Http 401 Unauthorized: Falha na autenticação da APIKey, verifique se o appId/appKey está correto.
  • Código de status 401: Chave de aplicativo inválida ou aplicativo não existe, verifique a configuração do aplicativo.

Erros de parâmetro

  • 400 Bad Request: Formato incorreto dos parâmetros da requisição.
  • Código de status 414: Parâmetro obrigatório ausente ou valor de parâmetro não atende aos requisitos.

Erros de operação de recursos

  • Código de status 404: Recurso alvo consultado não existe.
  • Código de status 403: Alvo já existe, não pode ser criado repetidamente.
  • Código de status 417/420/424: Falha nas operações de adição, exclusão ou modificação.

Erros relacionados a arquivos

  • Código de status 422: Tamanho do arquivo enviado excede o limite.
  • Código de status 427: Formato de imagem não suportado ou arquivo corrompido.

Erros de sistema

  • Http 500 Internal Server Error: Exceção interna do servidor, recomenda-se testar no site ou usando um sample.
  • Http 501 Exception: Exceção capturada na aplicação, possivelmente erro de dados, recomenda-se testar no site ou usando um sample.
  • Http 502 Server: Erro na resposta do serviço, possivelmente erro do servidor, recomenda-se contatar-nos.

Melhores práticas recomendadas

  1. Processamento no cliente: Recomenda-se usar o campo statusCode para determinar o sucesso da operação, não apenas o código de status HTTP.
  2. Repetição em caso de erro: Para erros 5xx, repetições moderadas são adequadas. Para erros 4xx, verifique os parâmetros da requisição.
  3. Registro de logs: Recomenda-se registrar a resposta completa de erro para facilitar a investigação de problemas.
  4. Tratamento de tempo limite: Configure um tempo limite de requisição razoável para evitar espera prolongada.