Tratamento de Erros

A API usa códigos de resposta HTTP convencionais para indicar o sucesso ou falha das solicitações. Esta página documenta formatos de erro e estratégias de tratamento.

Formatos de resposta de erro

O formato depende de onde o erro é gerado.

Erros de autenticação e de limite de taxa (401 e 429)

Um pequeno objeto JSON com error, message e status. Os endpoints de alteração de política, o endpoint de código QR de provisionamento e os endpoints de comando de dispositivo diferentes de lock, lost-mode, found e message são a exceção: o 429 deles usa o formato de detalhes do problema abaixo, com code e retryable.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded for device commands on this API key. Try again later.",
  "status": 429
}

Todos os outros erros (por exemplo, 400, 403, 409, 422, 500, 502 e 503)

Detalhes do problema segundo a RFC 9457 com o tipo de conteúdo application/problem+json. Erros de validação adicionam uma matriz errors. Os endpoints de alteração de política, o endpoint de código QR de provisionamento e os endpoints de comando de dispositivo diferentes de lock, lost-mode, found e message adicionam um membro code a todos os erros, exceto 401. No endpoint de código QR de provisionamento, um corpo que não seja um JSON válido ou tenha um campo desconhecido também é uma exceção: seu 400 não possui code. O membro retryable é descrito abaixo.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "VALIDATION_ERROR",
  "title": "Validation Error",
  "status": 400,
  "instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
  "errors": [
    { "field": "title", "index": null, "message": "must not be blank" }
  ]
}
CampoDescrição
typeTipo de erro, ou about:blank
titleResumo breve, como a frase de status HTTP
statusO código de status HTTP
detailExplicação legível para humanos deste erro
instanceO caminho da solicitação
errorsErros de validação no nível do campo, cada um com field, index e message (apenas 400)
codeUm código de erro estável para desvio condicional, como not_found, forbidden ou internal_error. Enviado pelos endpoints de alteração de política, pelo endpoint de código QR de provisionamento e pelos endpoints de comandos de dispositivo que não sejam lock, lost-mode, found e message.
retryabletrue se a mesma solicitação puder ser repetida. Enviado em 502 e 503 por todos os endpoints de comando de dispositivo, em 429 e 500 pelos endpoints de comando diferentes de lock, lost-mode, found e message, e em todos os erros que contêm um code dos endpoints de alteração de política e do endpoint de código QR de provisionamento.

Um 404 para um ativo ou política desconhecido tem um corpo vazio. Os endpoints de alteração de política, o endpoint de código QR de provisionamento e os endpoints de comando de dispositivo diferentes de lock, lost-mode, found e message são a exceção: o 404 deles é em detalhes do problema com o code not_found.

Os endpoints de sessão do Device User respondem a 400, 404 e 409 com application/problem+json e um membro code para ramificação; eles não enviam um membro retryable. Duas exceções não têm code: 401 e 403, e um 400 para um parâmetro de consulta inválido de GET /device-user-logins. API de sessões de Device User

Códigos de Status HTTP

CódigoDescrição
400Parâmetros de solicitação inválidos ou corpo da solicitação malformado
401Chave de API ausente ou inválida
403Chave de API não tem as permissões necessárias para este endpoint
404Recurso solicitado não existe
429Limite de taxa excedido - tente novamente após o tempo especificado
500Erro interno do servidor - contate o suporte se persistir
503Serviço temporariamente indisponível - tente novamente mais tarde

Respostas de comandos de dispositivos

Os endpoints de comando usam códigos de status com regras especiais de repetição. Tentar novamente no código errado pode entregar um comando a um dispositivo duas vezes.

202Resultado desconhecido. Não reenvie. Verifique o histórico de comandos primeiro.
500Erro inesperado, com código internal_error fora dos endpoints lock, lost-mode, found e message. Não se sabe se o comando alcançou o dispositivo. Verifique o dispositivo antes de tentar novamente.
503Não enviado. Seguro para tentar novamente.
502O provedor rejeitou o comando. Tente novamente apenas se retryable for true.
409O dispositivo não pode aceitar este comando. Tentar novamente falhará até que seu estado mude.
422O provedor recusou o comando. Não tente novamente com os mesmos argumentos.
HTTP/1.1 202 Accepted

{
  "assetId": "k3x9m2pa",
  "type": "LOCK",
  "status": "UNCONFIRMED",
  "detail": "The command's outcome is unknown. Check the device's command history (list_device_commands or GET /api/v1/assets/{assetId}/commands) before retrying; it may only appear once the device acknowledges it."
}
HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Command was not sent; it is safe to retry.",
  "instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
  "retryable": true
}

Referência completa de comandos de dispositivos

Estratégia de Tentativa

Tente novamente apenas quando for seguro. Solicitações de leitura que falharem com um erro temporário podem ser repetidas com backoff exponencial. Um comando de dispositivo deve seguir as regras da seção de respostas de comandos de dispositivo. Após um erro de alteração de política ou de código QR de provisionamento, siga o campo retryable e, após um erro inesperado em apply, leia a proposta antes de propor novamente.

  • Para erros 429, aguarde o número de segundos no cabeçalho Retry-After antes de tentar novamente.
  • Para erros 5xx em solicitações de leitura, use backoff exponencial (1s, 2s, 4s, 8s...) com jitter. Para comandos de dispositivo, tente novamente apenas um 503 (não enviado) ou um 502 com retryable definido como true. Após um 202 ou um 500, verifique o dispositivo antes de enviar novamente.
  • Defina uma contagem máxima de tentativas (ex: 3-5 tentativas) para evitar loops infinitos

Limitação de Taxa

Quando você excede o limite de solicitações MCP ou chama o endpoint lock, lost-mode, found ou message acima do limite de comandos, a API retorna HTTP 429 Too Many Requests com um cabeçalho Retry-After e um corpo JSON com error, message e status. Os outros endpoints de comando de dispositivo, os endpoints de alteração de política e o endpoint de código QR de provisionamento também enviam Retry-After acima do mesmo limite, mas o corpo deles é em detalhes do problema com o code rate_limited e retryable true. Quando uma chamada de comando MCP, alteração de política ou ferramenta de provisionamento excede o limite de comandos, o resultado é um erro de ferramenta cujo texto informa quantos segundos aguardar.

Use o cabeçalho Retry-After ou os segundos informados em um erro de ferramenta para decidir quando tentar novamente. A API não envia os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining ou X-RateLimit-Reset.

Erros de Validação

Para erros 400 causados por um corpo de solicitação inválido, os detalhes do problema incluem uma matriz errors com uma entrada por campo inválido. Outros erros 400, como um valor lastSeenBefore inválido, explicam o problema detalhadamente.

Melhores Práticas de Tratamento de Erros

  • Sempre verifique o código de status HTTP antes de processar o corpo da resposta
  • Siga Retry-After no 429 e use backoff exponencial para erros 5xx em solicitações de leitura. Para comandos de dispositivo, tente novamente apenas um 503 ou um 502 com retryable definido como true, e nunca reenvie após um 202 ou um 500 sem verificar o dispositivo primeiro.
  • Registre o status HTTP e o detail ou message do corpo do erro para depuração. Corpos de erro não incluem os campos timestamp ou path.
  • Trate códigos de erro específicos de forma diferente (ex: 401 aciona re-autenticação)

Escolha o seu horário

Carregando...
Abrir calendário de agendamento