Documentação de códigos de erro das APIs de mapas espaciais esparsos

Formato de resposta

Todas as respostas da API usam um formato JSON unificado. Aqui está um exemplo:

{

  "statusCode": 119,

  "msg": "Parameter has errors",

  "date": "2022-06-15T09:56:30.000Z",

  "result":  //Resultado só se o statusCode for 0, e se ocorrer um erro, o campo resultado estará vazio

}

Campo	Tipo	Descrição
statusCode	integer	Código de status do serviço, 0 indica sucesso, diferente de 0 indica erro
msg	string	Mensagem
result	object	Conteúdo retornado. Quando o código de status é 0, contém a estrutura do objeto do mapa alvo, caso contrário está vazio
date	string	Hora do servidor

Importante

Apenas quando statusCode == 0, o result inclui o conteúdo da resposta. Em outros estados, o result fica vazio
Quando statusCode != 0, preste atenção à mensagem de erro msg

Classificação dos códigos de erro

Explicação dos códigos de status HTTP

Código de status HTTP	Descrição
200	Solicitação bem-sucedida (pode conter erros de serviço)
400	Erro nos parâmetros da solicitação
401	Falha na autenticação da APIKey
403	Permissões insuficientes ou acesso ao recurso proibido
404	Caminho (Path) da URL solicitada não existe
500	Erro interno do servidor
502	Exceção capturada na aplicação, possível erro de dados

Atenção: Erros de serviço normalmente são retornados via resposta HTTP 200, identificados no campo statusCode.

Tabela de códigos de status de serviço

Status Code	Message
0	Success
101	Uploaded file is empty
102	File size is too large
106	Missing parameter or parameter is empty
110	Call server API errors
111	Resource not found
401	Authentication token expired
401	Authentication parameter is missing
401	Unknown appId or appKey
401	Account is locked
401	Authentication failed, invalid signature or token

Cenários comuns de erro

Tempo limite sem resposta

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 appId/appKey estão corretos
Código de status 401: Chave de aplicativo inválida ou aplicativo inexistente, verifique a configuração do aplicativo

Erros de parâmetro

400 Bad Request: Formato de parâmetro de solicitação incorreto

Erros de operação de recurso

Código de status 10x: Recurso alvo da consulta não existe ou parâmetro incorreto

Erros de sistema

Http 50x Internal Server Error: Exceção interna do servidor ou exceção capturada na aplicação, recomenda-se testar no site ou com amostra (sample)

Melhores práticas recomendadas

Tratamento no cliente: Recomenda-se usar o campo statusCode para determinar o sucesso da operação, não apenas depender do código de status HTTP
Repetição de erros: Para erros 5xx, pode-se tentar novamente; para erros 4xx, verifique os parâmetros da solicitação
Registro de logs: Recomenda-se registrar a resposta de erro completa para facilitar a solução de problemas
Tratamento de tempo limite: Defina um tempo limite de solicitação razoável para evitar esperas prolongadas

Table of Contents