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.

Códigos de Status HTTP

Códigos de Sucesso

Code	Description
200	Solicitação bem-sucedida. O corpo da resposta contém os dados solicitados.
201	Recurso criado com sucesso.

Códigos de Erro

Code	Description
400	Solicitação Inválida - Parâmetros inválidos ou corpo da solicitação malformado
401	Não Autorizado - Chave de API ausente ou inválida
403	Proibido - Chave de API não possui as permissões necessárias
404	Não Encontrado - Recurso solicitado não existe
429	Muitas Solicitações - Limite de taxa excedido
500	Erro Interno do Servidor - Contate o suporte se isso persistir

Formato de Resposta de Erro

Todas as respostas de erro seguem uma estrutura JSON consistente com um objeto de erro contendo campos de código, mensagem e detalhes.

Error Response Structurejson

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "details": "The X-API-Key header is required for authentication"
  }
}

Cenários de Erro Comuns

401

Chave de API Inválida

Este erro ocorre quando a chave de API está ausente, é inválida ou foi revogada. Verifique se você está incluindo o cabeçalho X-API-Key com uma chave válida.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "details": "The provided API key is invalid or has been revoked"
  }
}

403

Permissões Insuficientes

Este erro ocorre quando sua chave de API não possui as permissões necessárias para o endpoint solicitado. Contate seu administrador para atualizar as permissões da chave.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions",
    "details": "This API key does not have the DEVICES_READ permission"
  }
}

429

Limite de Taxa

Este erro ocorre quando você excedeu o limite de taxa. A resposta inclui informações sobre quando você pode tentar novamente.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "details": "Rate limit exceeded. Try again in 45 seconds"
  }
}

Melhores Práticas de Tratamento de Erros

Implemente tratamento de erros robusto em sua integração para lidar com falhas graciosamente e tentar novamente erros transitórios automaticamente.

Error Handling Example

import requests
import time

API_KEY = "nm_acme_abc123..."
BASE_URL = "https://api.nomid.tech/emm/api/v1"

def make_request(endpoint, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(
            f"{BASE_URL}{endpoint}",
            headers={"X-API-Key": API_KEY}
        )
        
        if response.status_code == 200:
            return response.json()
        
        if response.status_code == 401:
            raise Exception("Invalid API key")
        
        if response.status_code == 403:
            raise Exception("Insufficient permissions")
        
        if response.status_code == 429:
            # Get retry time from header or use default
            retry_after = int(response.headers.get("X-RateLimit-Reset", 60))
            wait_time = min(retry_after, 60)
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)
            continue
        
        if response.status_code >= 500:
            # Exponential backoff for server errors
            wait_time = (2 ** attempt) * 1
            print(f"Server error. Retrying in {wait_time}s...")
            time.sleep(wait_time)
            continue
        
        # Unknown error
        response.raise_for_status()
    
    raise Exception(f"Failed after {max_retries} retries")

Estratégia de Tentativa

Para erros transitórios, implemente uma estratégia de tentativa com backoff exponencial:

Para erros 429, aguarde o tempo especificado no cabeçalho X-RateLimit-Reset antes de tentar novamente
Para erros 5xx, use backoff exponencial (1s, 2s, 4s, 8s...) com variação
Defina uma contagem máxima de tentativas (ex: 3-5 tentativas) para evitar loops infinitos

Códigos de Status HTTP

Códigos de Sucesso

Code	Description
200	Solicitação bem-sucedida. O corpo da resposta contém os dados solicitados.
201	Recurso criado com sucesso.

Códigos de Erro

Code	Description
400	Solicitação Inválida - Parâmetros inválidos ou corpo da solicitação malformado
401	Não Autorizado - Chave de API ausente ou inválida
403	Proibido - Chave de API não possui as permissões necessárias
404	Não Encontrado - Recurso solicitado não existe
429	Muitas Solicitações - Limite de taxa excedido
500	Erro Interno do Servidor - Contate o suporte se isso persistir

Formato de Resposta de Erro

Todas as respostas de erro seguem uma estrutura JSON consistente com um objeto de erro contendo campos de código, mensagem e detalhes.

Error Response Structurejson

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "details": "The X-API-Key header is required for authentication"
  }
}

Cenários de Erro Comuns

401

Chave de API Inválida

Este erro ocorre quando a chave de API está ausente, é inválida ou foi revogada. Verifique se você está incluindo o cabeçalho X-API-Key com uma chave válida.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "details": "The provided API key is invalid or has been revoked"
  }
}

403

Permissões Insuficientes

Este erro ocorre quando sua chave de API não possui as permissões necessárias para o endpoint solicitado. Contate seu administrador para atualizar as permissões da chave.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions",
    "details": "This API key does not have the DEVICES_READ permission"
  }
}

429

Limite de Taxa

Este erro ocorre quando você excedeu o limite de taxa. A resposta inclui informações sobre quando você pode tentar novamente.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "details": "Rate limit exceeded. Try again in 45 seconds"
  }
}

Melhores Práticas de Tratamento de Erros

Implemente tratamento de erros robusto em sua integração para lidar com falhas graciosamente e tentar novamente erros transitórios automaticamente.

Error Handling Example

import requests
import time

API_KEY = "nm_acme_abc123..."
BASE_URL = "https://api.nomid.tech/emm/api/v1"

def make_request(endpoint, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(
            f"{BASE_URL}{endpoint}",
            headers={"X-API-Key": API_KEY}
        )
        
        if response.status_code == 200:
            return response.json()
        
        if response.status_code == 401:
            raise Exception("Invalid API key")
        
        if response.status_code == 403:
            raise Exception("Insufficient permissions")
        
        if response.status_code == 429:
            # Get retry time from header or use default
            retry_after = int(response.headers.get("X-RateLimit-Reset", 60))
            wait_time = min(retry_after, 60)
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)
            continue
        
        if response.status_code >= 500:
            # Exponential backoff for server errors
            wait_time = (2 ** attempt) * 1
            print(f"Server error. Retrying in {wait_time}s...")
            time.sleep(wait_time)
            continue
        
        # Unknown error
        response.raise_for_status()
    
    raise Exception(f"Failed after {max_retries} retries")

Estratégia de Tentativa

Para erros transitórios, implemente uma estratégia de tentativa com backoff exponencial:

Para erros 429, aguarde o tempo especificado no cabeçalho X-RateLimit-Reset antes de tentar novamente

Para erros 5xx, use backoff exponencial (1s, 2s, 4s, 8s...) com variação

Defina uma contagem máxima de tentativas (ex: 3-5 tentativas) para evitar loops infinitos