Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of requests. This page documents error formats and handling strategies.

HTTP Status Codes

Success Codes

Code	Description
200	Request succeeded. Response body contains the requested data.
201	Resource created successfully.

Error Codes

Code	Description
400	Bad Request - Invalid parameters or malformed request body
401	Unauthorized - Missing or invalid API key
403	Forbidden - API key lacks required permissions
404	Not Found - Requested resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Please contact support if this persists

Error Response Format

All error responses follow a consistent JSON structure with an error object containing code, message, and details fields.

Error Response Structurejson

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

Common Error Scenarios

401

Invalid API Key

This error occurs when the API key is missing, invalid, or has been revoked. Check that you're including the X-API-Key header with a valid key.

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

403

Insufficient Permissions

This error occurs when your API key doesn't have the required permissions for the requested endpoint. Contact your administrator to update key permissions.

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

429

Rate Limited

This error occurs when you've exceeded the rate limit. The response includes information about when you can retry.

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

Error Handling Best Practices

Implement robust error handling in your integration to gracefully handle failures and automatically retry transient errors.

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

Retry Strategy

For transient errors, implement a retry strategy with exponential backoff:

For 429 errors, wait for the time specified in the X-RateLimit-Reset header before retrying
For 5xx errors, use exponential backoff (1s, 2s, 4s, 8s...) with jitter
Set a maximum retry count (e.g., 3-5 attempts) to avoid infinite loops

HTTP Status Codes

Success Codes

Code	Description
200	Request succeeded. Response body contains the requested data.
201	Resource created successfully.

Error Codes

Code	Description
400	Bad Request - Invalid parameters or malformed request body
401	Unauthorized - Missing or invalid API key
403	Forbidden - API key lacks required permissions
404	Not Found - Requested resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Please contact support if this persists

Error Response Format

All error responses follow a consistent JSON structure with an error object containing code, message, and details fields.

Error Response Structurejson

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

Common Error Scenarios

401

Invalid API Key

This error occurs when the API key is missing, invalid, or has been revoked. Check that you're including the X-API-Key header with a valid key.

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

403

Insufficient Permissions

This error occurs when your API key doesn't have the required permissions for the requested endpoint. Contact your administrator to update key permissions.

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

429

Rate Limited

This error occurs when you've exceeded the rate limit. The response includes information about when you can retry.

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

Error Handling Best Practices

Implement robust error handling in your integration to gracefully handle failures and automatically retry transient errors.

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

Retry Strategy

For transient errors, implement a retry strategy with exponential backoff:

For 429 errors, wait for the time specified in the X-RateLimit-Reset header before retrying

For 5xx errors, use exponential backoff (1s, 2s, 4s, 8s...) with jitter

Set a maximum retry count (e.g., 3-5 attempts) to avoid infinite loops