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" }
]
} | Campo | Descrição |
|---|---|
| type | Tipo de erro, ou about:blank |
| title | Resumo breve, como a frase de status HTTP |
| status | O código de status HTTP |
| detail | Explicação legível para humanos deste erro |
| instance | O caminho da solicitação |
| errors | Erros de validação no nível do campo, cada um com field, index e message (apenas 400) |
| code | Um 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. |
| retryable | true 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ódigo | Descrição |
|---|---|
| 400 | Parâmetros de solicitação inválidos ou corpo da solicitação malformado |
| 401 | Chave de API ausente ou inválida |
| 403 | Chave de API não tem as permissões necessárias para este endpoint |
| 404 | Recurso solicitado não existe |
| 429 | Limite de taxa excedido - tente novamente após o tempo especificado |
| 500 | Erro interno do servidor - contate o suporte se persistir |
| 503 | Serviç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.
| 202 | Resultado desconhecido. Não reenvie. Verifique o histórico de comandos primeiro. |
|---|---|
| 500 | Erro 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. |
| 503 | Não enviado. Seguro para tentar novamente. |
| 502 | O provedor rejeitou o comando. Tente novamente apenas se retryable for true. |
| 409 | O dispositivo não pode aceitar este comando. Tentar novamente falhará até que seu estado mude. |
| 422 | O 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
} 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)