Error Codes

Complete reference for NetStacks API error responses including HTTP status codes, error formats, and resolution steps.

Overview

The NetStacks API returns consistent JSON error responses for all error conditions. Every error includes an HTTP status code, an error code string, a human-readable message, and optional details for field-level validation errors.

Understanding the error format lets you build robust integrations that handle failures gracefully, display meaningful messages to users, and implement automatic retry logic for transient errors.

Error Categories

Errors fall into five categories: authentication (401/403), validation (400/422), not found (404), conflict (409), and server (429/500/503). Each category has different handling strategies.

How It Works

Error Response Format

All API errors return a JSON object with the following structure:

error-format.jsonjson

{
  "error": {
    "code": "DEVICE_NOT_FOUND",
    "message": "Device with ID 'f47ac10b-58cc-4372-a567-0e02b2c3d479' not found",
    "status": 404,
    "details": null
  }
}

Validation Error Details

For 422 validation errors, the details field contains field-level information:

validation-error.jsonjson

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "status": 422,
    "details": {
      "field": "device_type",
      "value": "invalid_type",
      "message": "Unknown device type 'invalid_type'"
    }
  }
}

Error Codes Reference

HTTP Status	Error Code	Description	Resolution
400	`INVALID_REQUEST`	Malformed request body or invalid JSON	Check JSON syntax and Content-Type header
400	`BAD_REQUEST`	Invalid parameter value (e.g., bad cron expression)	Check the error message for the specific invalid parameter
401	`TOKEN_EXPIRED`	Access token has expired	Call `/api/auth/refresh` to get a new token
401	`INVALID_TOKEN`	Token is invalid, malformed, or revoked	Re-authenticate via `/api/auth/login`
401	`UNAUTHORIZED`	No authentication token provided	Include `Authorization: Bearer` header
403	`INSUFFICIENT_PERMISSIONS`	User lacks the required permission	Check role assignments in Admin > Users
404	`DEVICE_NOT_FOUND`	Device UUID does not exist	Verify the device ID with `GET /api/devices`
404	`TEMPLATE_NOT_FOUND`	Template UUID does not exist	Verify the template ID with `GET /api/templates`
404	`TASK_NOT_FOUND`	Scheduled task UUID does not exist	Verify the task ID with `GET /api/tasks/schedules`
409	`DUPLICATE_NAME`	Resource name already exists	Use a unique name or update the existing resource
422	`VALIDATION_ERROR`	Request failed field-level validation	Check `error.details` for the invalid field
422	`TEMPLATE_RENDER_ERROR`	Jinja2 template rendering failed	Check template syntax and provide all required variables
429	`RATE_LIMITED`	Too many requests	Wait and retry with exponential backoff
500	`INTERNAL_ERROR`	Unexpected server error	Check server logs, contact support
503	`SERVICE_UNAVAILABLE`	Server is starting or overloaded	Retry with exponential backoff

Step-by-Step Guide

How to Handle API Errors

Check the HTTP status code — Use the status code to determine the error category (4xx = client error, 5xx = server error).
Parse the error JSON — Read the error.code and error.message fields for specific error identification.
Switch on error.code — Handle specific error codes differently: refresh tokens on TOKEN_EXPIRED, fix input on VALIDATION_ERROR, retry on RATE_LIMITED.
Check error.details — For validation errors, the details field contains the specific field name, invalid value, and a descriptive message.
Implement retry logic — For 429 and 503 errors, use exponential backoff: wait 1s, 2s, 4s, 8s up to a maximum of 30 seconds.
Log for debugging — Always log the full error response body for debugging. Include the request ID if available.

Code Examples

Error Responses (curl)

error-examples.shbash

# 401 Unauthorized - expired token
curl -i https://netstacks.example.net/api/devices \
  -H "Authorization: Bearer expired-token-here"

# HTTP/1.1 401 Unauthorized
# {
#   "error": {
#     "code": "TOKEN_EXPIRED",
#     "message": "Access token has expired",
#     "status": 401,
#     "details": null
#   }
# }

# 422 Validation Error - invalid device type
curl -i -X POST https://netstacks.example.net/api/devices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "host": "10.0.1.1", "port": 22, "device_type": "not_real"}'

# HTTP/1.1 422 Unprocessable Entity
# {
#   "error": {
#     "code": "VALIDATION_ERROR",
#     "message": "Request validation failed",
#     "status": 422,
#     "details": {"field": "device_type", "value": "not_real", "message": "Unknown device type"}
#   }
# }

# 429 Rate Limited
# HTTP/1.1 429 Too Many Requests
# Retry-After: 60
# {
#   "error": {
#     "code": "RATE_LIMITED",
#     "message": "Too many requests, please try again later",
#     "status": 429,
#     "details": null
#   }
# }

Python Error Handling with Retry

error-handling.pypython

import requests
import time

class NetStacksApiError(Exception):
    def __init__(self, status: int, code: str, message: str, details=None):
        self.status = status
        self.code = code
        self.message = message
        self.details = details
        super().__init__(f"[{status}] {code}: {message}")

def api_request(method: str, url: str, headers: dict, max_retries=3, **kwargs):
    """Make an API request with automatic retry for transient errors."""
    for attempt in range(max_retries + 1):
        resp = requests.request(method, url, headers=headers, **kwargs)

        if resp.ok:
            return resp.json() if resp.content else None

        error_data = resp.json().get("error", {})
        code = error_data.get("code", "UNKNOWN")

        # Retry on rate limit or server errors
        if resp.status_code in (429, 503) and attempt < max_retries:
            wait = min(2 ** attempt, 30)
            print(f"Retrying in {wait}s ({code})...")
            time.sleep(wait)
            continue

        # Token expired - could auto-refresh here
        if code == "TOKEN_EXPIRED":
            raise NetStacksApiError(401, code, "Token expired - refresh needed")

        raise NetStacksApiError(
            resp.status_code, code,
            error_data.get("message", "Unknown error"),
            error_data.get("details")
        )

# Usage
try:
    devices = api_request("GET", f"{base_url}/devices", headers=headers)
except NetStacksApiError as e:
    if e.code == "VALIDATION_ERROR":
        print(f"Validation failed on field: {e.details.get('field')}")
    else:
        print(f"API error: {e}")

TypeScript Error Handling with Retry

error-handling.tstypescript

interface ApiError {
  error: {
    code: string;
    message: string;
    status: number;
    details?: { field?: string; value?: string; message?: string } | null;
  };
}

class NetStacksError extends Error {
  constructor(
    public status: number,
    public code: string,
    public details?: ApiError["error"]["details"]
  ) {
    super(`[${status}] ${code}`);
  }
}

async function apiRequest<T>(
  method: string,
  url: string,
  headers: Record<string, string>,
  options?: { body?: string; maxRetries?: number }
): Promise<T> {
  const maxRetries = options?.maxRetries ?? 3;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const resp = await fetch(url, { method, headers, body: options?.body });

    if (resp.ok) {
      return resp.status === 204 ? (null as T) : resp.json();
    }

    const errorData: ApiError = await resp.json();
    const { code, details } = errorData.error;

    // Retry on transient errors
    if ((resp.status === 429 || resp.status === 503) && attempt < maxRetries) {
      const wait = Math.min(2 ** attempt * 1000, 30000);
      console.warn(`Retrying in ${wait}ms (${code})...`);
      await new Promise((r) => setTimeout(r, wait));
      continue;
    }

    throw new NetStacksError(resp.status, code, details);
  }

  throw new Error("Max retries exceeded");
}

// Usage
try {
  const devices = await apiRequest("GET", `${BASE_URL}/devices`, headers);
} catch (e) {
  if (e instanceof NetStacksError) {
    if (e.code === "TOKEN_EXPIRED") {
      console.log("Refreshing token...");
    } else if (e.code === "VALIDATION_ERROR") {
      console.log(`Invalid field: ${e.details?.field}`);
    }
  }
}

Questions & Answers

What format do API errors return?: All errors return a JSON object with an error field containing code (string), message (human-readable), status (HTTP status code), and optional details (field-level info for validation errors).
How do I handle token expiration?: When you receive a 401 with code TOKEN_EXPIRED, call POST /api/auth/refresh with your refresh token to get a new access token. If the refresh token is also expired, re-authenticate via /api/auth/login.
What does a 422 validation error look like?: A 422 error includes a details field with the specific field name that failed validation, the invalid value, and a descriptive message. Use this to display field-specific error messages in your UI.
How should I handle rate limiting?: When you receive a 429 response, implement exponential backoff: wait 1 second, then 2, then 4, up to 30 seconds max. The response may include a Retry-After header with the recommended wait time.
How do I debug a 500 Internal Server Error?: A 500 error indicates an unexpected server-side issue. Check the Controller logs for the full error trace. If the error persists, report it with the request details (method, URL, body) and the error response body.
Are error codes stable across API versions?: Yes. Error codes like DEVICE_NOT_FOUND, VALIDATION_ERROR, and TOKEN_EXPIRED are stable and safe to match on in your code. New codes may be added in future versions but existing codes will not change.

Troubleshooting

Getting 401 on Every Request

The token is either not included, expired, or malformed. Verify the Authorization: Bearer <token> header is present and the token is a valid JWT. Use the auth endpoint to get a fresh token.

403 After Token Refresh

The user's role or permissions were changed after the original token was issued. The refreshed token reflects the current permissions. Check if the user's roles still include the required permission for the operation.

422 on Device Creation

Check that all required fields are provided: name, host, port, and device_type. The error.details field identifies exactly which field failed validation and why.

429 in Automated Scripts

Your script is sending requests too quickly. Add rate limiting to your client: space requests at least 100ms apart and implement exponential backoff on 429 responses. Consider batching operations where possible.

500 Errors During Deployments

Internal errors during stack deployments may indicate database connectivity issues, SSH connection failures, or resource exhaustion. Check the Controller logs and the deployment status endpoint for device-level error details.

API Authentication — Authentication flow and token management.
Devices API — Device management endpoints.
Templates API — Template management and rendering.
Stacks API — Stack deployment and management.
Tasks API — Scheduled task management.