API Error Codes

This reference documents all error codes returned by the IronWiFi REST API, their meanings, and how to resolve them. Use this guide when your API integration encounters an error response.

Error Response Format

All API errors return a JSON response with a consistent structure:

{
  "error": true,
  "message": "Human-readable error description",
  "code": 400
}

Field	Type	Description
`error`	boolean	Always `true` for error responses
`message`	string	Description of what went wrong
`code`	integer	HTTP status code matching the response status

Some error responses include additional fields for more context:

{
  "error": true,
  "message": "Validation failed",
  "code": 400,
  "details": [
    {"field": "username", "error": "Username is required"},
    {"field": "email", "error": "Invalid email format"}
  ]
}

HTTP Status Codes

2xx Success

Code	Meaning	When Returned
`200 OK`	Request succeeded	GET, PUT, DELETE operations
`201 Created`	Resource created	POST operations that create new resources
`204 No Content`	Request succeeded, no response body	DELETE operations

4xx Client Errors

Code	Meaning	Common Cause
`400 Bad Request`	Invalid request data	Missing required fields, invalid format
`401 Unauthorized`	Authentication failed	Missing, invalid, or expired API key
`403 Forbidden`	Insufficient permissions	API key lacks access to the requested resource
`404 Not Found`	Resource does not exist	Incorrect resource ID or endpoint URL
`405 Method Not Allowed`	HTTP method not supported	Using POST on a GET-only endpoint
`409 Conflict`	Resource conflict	Duplicate username, conflicting update
`422 Unprocessable Entity`	Valid JSON but invalid content	Business logic validation failure
`429 Too Many Requests`	Rate limit exceeded	Too many requests in the current window

5xx Server Errors

Code	Meaning	Action
`500 Internal Server Error`	Unexpected server error	Retry after a delay; contact support if persistent
`502 Bad Gateway`	Upstream service unavailable	Retry after a delay
`503 Service Unavailable`	Service temporarily down	Retry after a delay; check status.ironwifi.com
`504 Gateway Timeout`	Request timed out	Retry with a simpler query or smaller payload

Detailed Error Reference

400 Bad Request

The request body is malformed or missing required fields.

Examples:

// Missing required field
{
  "error": true,
  "message": "Username is required",
  "code": 400
}

// Invalid field format
{
  "error": true,
  "message": "Invalid email format: 'not-an-email'",
  "code": 400
}

// Malformed JSON
{
  "error": true,
  "message": "Invalid JSON in request body",
  "code": 400
}

How to fix:

Verify all required fields are included in the request body
Check that field values match the expected format
Validate your JSON syntax before sending
Ensure
```
Content-Type: application/json
```
header is set

401 Unauthorized

Authentication failed. The API key is missing, invalid, or expired.

{
  "error": true,
  "message": "Invalid or missing API key",
  "code": 401
}

How to fix:

Verify the
```
Authorization: Bearer YOUR_API_KEY
```
header is present
Check that the API key is correct (no extra spaces or truncated characters)
Generate a new API key if the current one may be compromised
See API Authentication for key management

403 Forbidden

The API key is valid but does not have permission to access the requested resource.

{
  "error": true,
  "message": "Insufficient permissions for this operation",
  "code": 403
}

How to fix:

Verify the API key has the required permissions
Check that you are accessing resources within your account scope
Contact your account administrator if you need elevated permissions

404 Not Found

The requested resource does not exist.

{
  "error": true,
  "message": "User not found",
  "code": 404
}

How to fix:

Verify the resource ID is correct
Check the endpoint URL for typos
Confirm the resource has not been deleted

List resources first to find the correct ID:

curl -X GET "https://console.ironwifi.com/api/users" \
  -H "Authorization: Bearer YOUR_API_KEY"

409 Conflict

The request conflicts with the current state of a resource.

{
  "error": true,
  "message": "Username 'john.doe' already exists",
  "code": 409
}

How to fix:

For duplicate usernames: use a different username or update the existing user
For concurrent updates: fetch the current state and retry with the latest data
Check for existing resources before creating new ones

422 Unprocessable Entity

The request is syntactically valid JSON but fails business logic validation.

{
  "error": true,
  "message": "Validation failed",
  "code": 422,
  "details": [
    {"field": "session_timeout", "error": "Must be a positive integer"},
    {"field": "bandwidth_limit", "error": "Exceeds maximum allowed value"}
  ]
}

How to fix:

Review the
```
details
```
array for specific field-level errors
Check value ranges and constraints in the API Endpoints documentation
Ensure numerical values are positive integers where required
Verify RADIUS attribute names and operators are valid

429 Too Many Requests

You have exceeded the API rate limit.

{
  "error": true,
  "message": "Rate limit exceeded. Try again in 45 seconds.",
  "code": 429
}

The response includes a

Retry-After

header indicating how many seconds to wait:

Retry-After: 45

How to fix:

Wait for the duration specified in the
```
Retry-After
```
header
Implement exponential backoff in your client
Reduce request frequency
Use bulk operations where available
See Rate Limiting for limits and best practices

500 Internal Server Error

An unexpected error occurred on the server.

{
  "error": true,
  "message": "Internal server error",
  "code": 500
}

How to fix:

Retry the request after a short delay (30-60 seconds)
If the error persists, check status.ironwifi.com for incidents
Contact support@ironwifi.com with the request details and timestamp

Error Handling Best Practices

Implement retry logic

For transient errors (429, 500, 502, 503, 504), implement automatic retries with exponential backoff:

import requests
import time

def api_request(method, url, headers, json=None, max_retries=3):
    """Make an API request with automatic retry for transient errors."""
    retryable_codes = {429, 500, 502, 503, 504}

    for attempt in range(max_retries + 1):
        response = requests.request(
            method, url, headers=headers, json=json
        )

        if response.status_code not in retryable_codes:
            return response

        if attempt < max_retries:
            if response.status_code == 429:
                wait = int(response.headers.get("Retry-After", 60))
            else:
                wait = min(2 ** attempt * 10, 120)

            print(f"Retrying in {wait}s "
                  f"(attempt {attempt + 1}/{max_retries})")
            time.sleep(wait)

    return response  # Return last response after all retries

Validate before sending

Reduce errors by validating data before making API calls:

def create_user(username, email, fullname):
    """Create a user with input validation."""
    # Validate required fields
    if not username or not username.strip():
        raise ValueError("Username is required")

    if email and "@" not in email:
        raise ValueError(f"Invalid email format: {email}")

    return api_request(
        "POST",
        f"{BASE_URL}/users",
        headers=HEADERS,
        json={
            "username": username.strip(),
            "email": email.strip() if email else "",
            "fullname": fullname.strip() if fullname else ""
        }
    )

Log errors for debugging

Always log API errors with enough context to diagnose issues:

import logging

logger = logging.getLogger("ironwifi_api")

def handle_response(response, context=""):
    """Log and handle API response."""
    if response.status_code >= 400:
        error_data = response.json()
        logger.error(
            "API error: %s %s - %d: %s",
            context,
            response.url,
            response.status_code,
            error_data.get("message", "Unknown error")
        )
        if "details" in error_data:
            for detail in error_data["details"]:
                logger.error("  Field '%s': %s",
                             detail["field"], detail["error"])

    return response

RADIUS-Specific Error Codes

When working with RADIUS authentication via the API, you may encounter these RADIUS-specific reject reasons in reports and webhook payloads:

Reject Reason	Meaning	Resolution
`Invalid credentials`	Username or password incorrect	Verify user credentials in the Console
`User disabled`	Account is deactivated	Enable the user account
`Account expired`	Valid-To date has passed	Update the user's validity dates
`Login time restriction`	Outside allowed login hours	Check Login-Time attribute
`Max sessions exceeded`	Simultaneous-Use limit reached	Wait for existing session to end or increase limit
`Unknown user`	Username not found	Create the user or check for typos

REST API -- API overview and base URLs
API Authentication -- API key management
API Endpoints -- Complete endpoint reference
Rate Limiting -- Rate limits and quotas
Webhooks -- Webhook event reference
Troubleshooting -- General troubleshooting guide

Was this page helpful?

Error Response Format​

HTTP Status Codes​

2xx Success​

4xx Client Errors​

5xx Server Errors​

Detailed Error Reference​

400 Bad Request​

401 Unauthorized​

403 Forbidden​

404 Not Found​

409 Conflict​

422 Unprocessable Entity​

429 Too Many Requests​

500 Internal Server Error​

Error Handling Best Practices​

Implement retry logic​

Validate before sending​

Log errors for debugging​

RADIUS-Specific Error Codes​

Related Topics​

Error Response Format

HTTP Status Codes

2xx Success

4xx Client Errors

5xx Server Errors

Detailed Error Reference

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Error Handling Best Practices

Implement retry logic

Validate before sending

Log errors for debugging

RADIUS-Specific Error Codes

Related Topics