Manejo de Errores

La API usa códigos de respuesta HTTP convencionales para indicar el éxito o fracaso de las solicitudes. Esta página documenta formatos de error y estrategias de manejo.

Códigos de Estado HTTP

Códigos de Éxito

Code	Description
200	Solicitud exitosa. El cuerpo de la respuesta contiene los datos solicitados.
201	Recurso creado exitosamente.

Códigos de Error

Code	Description
400	Solicitud Incorrecta - Parámetros inválidos o cuerpo de solicitud malformado
401	No Autorizado - Clave API faltante o inválida
403	Prohibido - La clave API carece de los permisos requeridos
404	No Encontrado - El recurso solicitado no existe
429	Demasiadas Solicitudes - Límite de velocidad excedido
500	Error Interno del Servidor - Contacta soporte si esto persiste

Formato de Respuesta de Error

Todas las respuestas de error siguen una estructura JSON consistente con un objeto de error que contiene campos de código, mensaje y detalles.

Error Response Structurejson

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

Escenarios de Error Comunes

401

Clave API Inválida

Este error ocurre cuando la clave API está faltante, es inválida o ha sido revocada. Verifica que estás incluyendo el encabezado X-API-Key con una clave válida.

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

403

Permisos Insuficientes

Este error ocurre cuando tu clave API no tiene los permisos requeridos para el endpoint solicitado. Contacta a tu administrador para actualizar los permisos de la clave.

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

429

Límite de Velocidad

Este error ocurre cuando has excedido el límite de velocidad. La respuesta incluye información sobre cuándo puedes reintentar.

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

Mejores Prácticas de Manejo de Errores

Implementa manejo de errores robusto en tu integración para manejar fallos con gracia y reintentar automáticamente errores transitorios.

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")

Estrategia de Reintento

Para errores transitorios, implementa una estrategia de reintento con retroceso exponencial:

Para errores 429, espera el tiempo especificado en el encabezado X-RateLimit-Reset antes de reintentar
Para errores 5xx, usa retroceso exponencial (1s, 2s, 4s, 8s...) con variación
Establece un conteo máximo de reintentos (ej. 3-5 intentos) para evitar bucles infinitos

Códigos de Estado HTTP

Códigos de Éxito

Code	Description
200	Solicitud exitosa. El cuerpo de la respuesta contiene los datos solicitados.
201	Recurso creado exitosamente.

Códigos de Error

Code	Description
400	Solicitud Incorrecta - Parámetros inválidos o cuerpo de solicitud malformado
401	No Autorizado - Clave API faltante o inválida
403	Prohibido - La clave API carece de los permisos requeridos
404	No Encontrado - El recurso solicitado no existe
429	Demasiadas Solicitudes - Límite de velocidad excedido
500	Error Interno del Servidor - Contacta soporte si esto persiste

Formato de Respuesta de Error

Todas las respuestas de error siguen una estructura JSON consistente con un objeto de error que contiene campos de código, mensaje y detalles.

Error Response Structurejson

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

Escenarios de Error Comunes

401

Clave API Inválida

Este error ocurre cuando la clave API está faltante, es inválida o ha sido revocada. Verifica que estás incluyendo el encabezado X-API-Key con una clave válida.

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

403

Permisos Insuficientes

Este error ocurre cuando tu clave API no tiene los permisos requeridos para el endpoint solicitado. Contacta a tu administrador para actualizar los permisos de la clave.

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

429

Límite de Velocidad

Este error ocurre cuando has excedido el límite de velocidad. La respuesta incluye información sobre cuándo puedes reintentar.

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

Mejores Prácticas de Manejo de Errores

Implementa manejo de errores robusto en tu integración para manejar fallos con gracia y reintentar automáticamente errores transitorios.

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")

Estrategia de Reintento

Para errores transitorios, implementa una estrategia de reintento con retroceso exponencial:

Para errores 429, espera el tiempo especificado en el encabezado X-RateLimit-Reset antes de reintentar

Para errores 5xx, usa retroceso exponencial (1s, 2s, 4s, 8s...) con variación

Establece un conteo máximo de reintentos (ej. 3-5 intentos) para evitar bucles infinitos