Error codes

This page explains how errors are returned by the Azerion Intelligence API, lists all possible error codes with their exact response formats, and provides guidance on handling them properly in your applications.

Error Response Format

When an API request fails, Azerion Intelligence returns:

An appropriate HTTP status code
A JSON response body with error details in the following structure:

{
  "error": {
    "message": "Description of what went wrong",
    "type": "error_type",
    "code": "specific_error_code", 
    "status_code": 400
  }
}

Error Properties

The error object in the response typically contains these fields:

message (string): A human-readable description of what went wrong.
type (string): A broad category of the error.
code (string): A specific error code that can be used for programmatic handling.
param (string, optional): When relevant, the specific parameter that caused the error.
status_code (integer): The HTTP status code for the error.

HTTP Status Code Reference

Status Code	Description	Common Causes	Resolution
400	Bad Request	Malformed JSON, missing required fields, invalid field values	Check your request format and required fields
401	Unauthorized	Invalid API key, expired key, or key not provided	Verify your API key is correct and included in the Authorization header
403	Forbidden	Valid API key but insufficient permissions	Check if your API key has the necessary permissions
404	Not Found	Requested resource (e.g., model) doesn't exist	Verify the resource identifier is correct
422	Unprocessable Entity	Request format is valid but semantically incorrect	Check the semantics of your request parameters
429	Too Many Requests	Rate limit exceeded	Implement backoff and retry logic
500	Internal Server Error	Server-side issue	Try again later, if persistent contact support
503	Service Unavailable	Service temporarily unavailable	Try again later with exponential backoff

Authentication Errors (401)

Unauthorized

Description: Basic authentication failure.

Response:

{
  "error": {
    "message": "Unauthorized.",
    "type": "unauthorized",
    "status_code": 401
  }
}

Common Causes:

Invalid API key format
Expired API key
Incorrect authentication method

Solution: Verify your API key is valid and properly formatted in the Authorization header.

Unauthorized API Key

Description: The provided API key is incorrect or invalid.

Response:

{
  "error": {
    "message": "Incorrect API key provided: ***. You can find your API key at https://azerion.ai/account/api-tokens.",
    "code": "invalid_api_key",
    "type": "invalid_request_error",
    "status_code": 401
  }
}

Common Causes:

Typo in the API key
Using a revoked or deleted API key
API key from wrong account/organization

Solution:

Check your API key for typos
Generate a new API key at https://azerion.ai/account/api-tokens
Update your application with the correct key

Missing API Key

Description: No API key was provided in the request.

Response:

{
  "error": {
    "message": "You didn't provide an API key. You need to provide your API key in an Authorization header using Bearer auth (i.e. Authorization: Bearer YOUR_KEY), or as the password field (with blank username) if you're accessing the API from your browser and are prompted for a username and password. You can obtain an API key from https://azerion.ai/account/api-tokens.",
    "type": "invalid_request_error",
    "status_code": 401
  }
}

Common Causes:

Forgot to include Authorization header
Incorrect header format
API key not loaded from environment variable

Solution:

Add the Authorization header: Authorization: Bearer YOUR_API_KEY
Obtain an API key from https://azerion.ai/account/api-tokens
See the Authentication guide for detailed setup instructions

Permission Errors (403)

Forbidden

Description: Access to the requested resource is denied.

Response:

{
  "error": {
    "message": "Access denied.",
    "type": "access denied",
    "status_code": 403
  }
}

Common Causes:

API key doesn't have permission for the requested resource
Account limitations or restrictions
Attempting to access restricted models or features

Solution:

Check if your account has access to the requested resource
Verify your subscription plan includes the feature you're trying to use
Contact support if you believe you should have access

Resource Errors (404)

Model Not Found

Description: The requested model doesn't exist or you don't have access to it.

Response:

{
  "error": {
    "message": "The model does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": null,
    "status_code": 404
  }
}

Common Causes:

Typo in the model name
Using a deprecated or removed model
Model not available in your account tier

Solution:

Check the model name for typos
Use the List Models endpoint to see available models
Verify your account has access to the requested model

Rate Limiting Errors (429)

Insufficient Quota

Description: You have exceeded your current usage quota.

Response:

{
  "error": {
    "message": "You exceeded your current quota, please check your plan and billing details",
    "code": "insufficient_quota",
    "type": "insufficient_quota",
    "status_code": 429
  }
}

Common Causes:

Monthly token limit reached
Account spending limit exceeded
Free tier quota exhausted

Solution:

Check your usage dashboard for current quota status
Upgrade your plan for higher limits
Review your billing details and payment method
Wait for quota reset (if monthly limit)

Too Many Requests

Description: You are being rate limited due to too many requests in a short time period.

Response:

{
  "error": {
    "message": "You are being rate limited.",
    "code": "insufficient_quota",
    "type": "insufficient_quota",
    "status_code": 429
  }
}

Common Causes:

Sending requests too quickly
Exceeding requests per minute/second limits
Concurrent request limits exceeded

Solution:

Implement exponential backoff in your retry logic
Add delays between requests
Check rate limits in the response headers
Consider upgrading to a plan with higher rate limits

Request Validation Errors (400)

Missing Required Parameters

Missing Model Parameter

Description: The model parameter is required but was not provided.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "model",
  "code": "missing_required_parameter",
  "message": "Missing required parameter: 'model'."
}

Common Causes:

Request payload missing the model field
Empty or null model value

Solution: Always include a valid model parameter in your request.

Missing Model Parameter (Alternative)

Description: Alternative format for missing model parameter error.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": null,
  "code": null,
  "message": "you must provide a model parameter"
}

Missing Prompt Parameter

Description: The prompt parameter is required for text-to-image and text-to-video endpoints.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "prompt",
  "code": "missing_required_parameter",
  "message": "Missing required parameter: 'prompt'."
}

Solution: Include a prompt parameter in your text-to-image or text-to-video requests.

Missing Input Parameter

Description: The input parameter is required for text-to-speech endpoints.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "input",
  "code": "missing_required_parameter",
  "message": "Missing required parameter: 'input'."
}

Solution: Include an input parameter in your text-to-speech requests.

Message Structure Errors

Invalid Role

Description: Invalid role value in the messages array.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "messages[0].role",
  "code": "invalid_value",
  "message": "Invalid value: 'messages[0].role'. Supported values are: '[user system developer tool assistant]'."
}

Common Causes:

Using unsupported role values
Typos in role names

Solution: Use only supported roles: user, system, developer, tool, assistant.

Missing Tool Calls in Assistant Role

Description: Assistant role message is missing required tool_calls when expected.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "messages.[0].tool_calls",
  "code": null,
  "message": "Invalid value for 'tool_calls': got null."
}

Solution: Provide tool_calls when using assistant role in tool calling scenarios.

Missing Content in Non-Assistant Role

Description: Non-assistant role message is missing required content.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "messages.[0].content",
  "code": null,
  "message": "Invalid value for 'content': expected a string, got null."
}

Solution: Always provide content for user, system, developer, and tool role messages.

Parameter Range Validation Errors

Temperature Validation

Temperature Too Low:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "temperature",
  "code": "decimal_below_min_value",
  "message": "Invalid 'temperature': decimal below minimum value. Expected a value >= 0, but got -0.5 instead."
}

Temperature Too High:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "temperature",
  "code": "decimal_above_max_value",
  "message": "Invalid 'temperature': decimal above maximum value. Expected a value <= 2, but got 2.5 instead."
}

Solution: Use temperature values between 0 and 2.

Frequency Penalty Validation

Frequency Penalty Too Low:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "frequency_penalty",
  "code": "decimal_below_min_value",
  "message": "Invalid 'frequency_penalty': decimal below minimum value. Expected a value >= -2, but got -3 instead."
}

Frequency Penalty Too High:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "frequency_penalty",
  "code": "decimal_above_max_value",
  "message": "Invalid 'frequency_penalty': decimal above maximum value. Expected a value <= 2, but got 3 instead."
}

Solution: Use frequency_penalty values between -2 and 2.

Top Logprobs Validation

Top Logprobs Too Low:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "top_logprobs",
  "code": "decimal_below_min_value",
  "message": "Invalid 'top_logprobs': decimal below minimum value. Expected a value >= 0, but got -1 instead."
}

Top Logprobs Too High:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "top_logprobs",
  "code": "decimal_above_max_value",
  "message": "Invalid 'top_logprobs': decimal above maximum value. Expected a value <= 20, but got 21 instead."
}

Solution: Use top_logprobs values between 0 and 20.

Speed Validation (Text-to-Speech)

Speed Too Low:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "speed",
  "code": "decimal_below_min_value",
  "message": "Invalid 'speed': decimal below minimum value. Expected a value >= 0.25, but got 0.1 instead."
}

Speed Too High:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "speed",
  "code": "decimal_above_max_value",
  "message": "Invalid 'speed': decimal above maximum value. Expected a value <= 4, but got 4.5 instead."
}

Solution: Use speed values between 0.25 and 4.0 for text-to-speech requests.

N Parameter Validation

N Too Low:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "n",
  "code": "decimal_below_min_value",
  "message": "Invalid 'n': decimal below minimum value. Expected a value >= 0, but got -1 instead."
}

N Too High:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "n",
  "code": "decimal_above_max_value",
  "message": "Invalid 'n': decimal above maximum value. Expected a value <= 10, but got 11 instead."
}

Solution: Use n values between 0 and 10.

Output Compression Validation (Text-to-Image)

Output Compression Too Low:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "output_compression",
  "code": "decimal_below_min_value",
  "message": "Invalid 'output_compression': decimal below minimum value. Expected a value >= 0, but got -1 instead."
}

Output Compression Too High:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "output_compression",
  "code": "decimal_above_max_value",
  "message": "Invalid 'output_compression': decimal above maximum value. Expected a value <= 10, but got 11 instead."
}

Solution: Use output_compression values between 0 and 10.

Logit Bias Validation Errors

Invalid Logit Bias Key (Non-Integer)

Description: Logit bias key must be a non-negative integer.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "logit_bias",
  "code": null,
  "message": "Invalid key in 'logit_bias': foo. You should only be submitting non-negative integers."
}

Solution: Use only non-negative integer keys in logit_bias.

Invalid Logit Bias Key (Too Large)

Description: Logit bias key exceeds maximum allowed value.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "logit_bias",
  "code": null,
  "message": "Invalid key in 'logit_bias': 100258. Maximum value is 100257."
}

Solution: Use logit_bias keys with values ≤ 100257.

Invalid Logit Bias Value

Description: Logit bias value is outside the allowed range.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "logit_bias",
  "code": null,
  "message": "Logit bias value 120 is invalid or outside of range [-100, 100]"
}

Solution: Use logit_bias values between -100 and 100.

Enum Validation Errors

Invalid Voice (Text-to-Speech)

Description: Invalid voice parameter for text-to-speech requests.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "voice",
  "code": "invalid_value",
  "message": "Invalid value: 'voice'. Supported values are: '[alloy ash ballad coral echo fable onyx nova sage shimmer verse ]'."
}

Solution: Use one of the supported voice values for text-to-speech requests.

Invalid Modality Value

Description: Invalid modality parameter value.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "modalities[0]",
  "code": "invalid_value",
  "message": "Invalid value: 'modalities[0]'. Supported values are: '[text]'."
}

Solution: Use only supported modality values.

Invalid Background Value (Text-to-Image)

Description: Invalid background parameter for image generation.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "background",
  "code": "invalid_value",
  "message": "Invalid value: 'background'. Supported values are: '[transparent opaque auto ]'."
}

Solution: Use supported background values: transparent, opaque, auto.

Invalid Moderation Value (Text-to-Image)

Description: Invalid moderation parameter for image generation.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "moderation",
  "code": "invalid_value",
  "message": "Invalid value: 'moderation'. Supported values are: '[low auto ]'."
}

Solution: Use supported moderation values: low, auto.

Invalid Output Format (Text-to-Image)

Description: Invalid output_format parameter for image generation.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "output_format",
  "code": "invalid_value",
  "message": "Invalid value: 'output_format'. Supported values are: '[png jpeg webp ]'."
}

Solution: Use supported output formats: png, jpeg, webp.

Invalid Size Value (Text-to-Image)

Description: Invalid size parameter for image generation.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "size",
  "code": "invalid_value",
  "message": "Invalid value: 'size'. Supported values are: '[auto 1024x1024 1536x1024 1024x1536 256x256 512x512 1792x1024 1024x1792 ]'."
}

Solution: Use supported size values: auto, 1024x1024, 1536x1024, 1024x1536, 256x256, 512x512, 1792x1024, 1024x1792.

Invalid Style Value (Text-to-Image)

Description: Invalid style parameter for image generation.

Response:

{
  "status_code": 400,
  "type": "invalid_request_error",
  "param": "style",
  "code": "invalid_value",
  "message": "Invalid value: 'style'. Supported values are: '[vivid natural ]'."
}

Solution: Use supported style values: vivid, natural.

Server Errors (500)

Internal Server Error

Description: An unexpected error occurred on the server side.

Response:

{
  "error": {
    "message": "The server had an error processing your request. Sorry about that! You can retry your request, or contact us support@azerion.ai if you keep seeing this error.",
    "code": "application_error",
    "type": "application_error",
    "status_code": 500
  }
}

Common Causes:

Temporary server issues
Service maintenance
Unexpected system problems

Solution:

Retry your request - Most 500 errors are temporary
Wait a few seconds before retrying
If the error persists, contact support at support@azerion.ai
Include the error details and your request information when contacting support

Error Handling Best Practices

Implement Retry Logic

For transient errors (like rate limits or temporary server issues), implement retry logic with exponential backoff:

import requests
import time

def make_request_with_retry(url, headers, data, max_retries=5):
    retries = 0
    while retries < max_retries:
        try:
            response = requests.post(url, headers=headers, json=data)
            
            # If successful, return the response
            if response.status_code == 200:
                return response.json()
            
            # If rate limited, wait and retry
            if response.status_code == 429:
                # Get retry time from headers if available, otherwise use exponential backoff
                retry_after = int(response.headers.get('Retry-After', 2 ** retries))
                print(f"Rate limited. Retrying in {retry_after} seconds...")
                time.sleep(retry_after)
                retries += 1
                continue
            
            # For other errors, raise an exception
            response.raise_for_status()
            
        except requests.exceptions.RequestException as e:
            if retries >= max_retries - 1:
                raise e
            
            # Exponential backoff for other errors
            sleep_time = 2 ** retries
            print(f"Request failed. Retrying in {sleep_time} seconds...")
            time.sleep(sleep_time)
            retries += 1
    
    raise Exception(f"Failed after {max_retries} retries")

Gracefully Handle API Errors

Design your application to gracefully handle API errors:

async function callApiWithErrorHandling(data) {
  try {
    const response = await fetch('https://api.azerion.ai/v1/chat/completions', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      body: JSON.stringify(data)
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      
      // Handle different error types
      switch (errorData.error?.type) {
        case 'invalid_request_error':
          // Handle invalid requests
          console.error('Invalid request:', errorData.error.message);
          break;
          
        case 'unauthorized':
          // Handle auth errors (e.g., redirect to login)
          console.error('Authentication failed:', errorData.error.message);
          break;
          
        case 'insufficient_quota':
          // Handle rate limits and quota issues
          console.error('Rate limited or quota exceeded:', errorData.error.message);
          // Wait and retry
          break;
          
        default:
          // Handle other errors
          console.error('API error:', errorData.error?.message || 'Unknown error');
      }
      
      return { error: errorData.error };
    }
    
    return await response.json();
  } catch (error) {
    // Handle network or parsing errors
    console.error('Request failed:', error);
    return { error: { message: error.message, type: 'client_error' } };
  }
}

Log Errors Appropriately

Log errors for debugging but be careful not to log sensitive information:

function logApiError(error, requestData) {
  // Sanitize the request data to remove any sensitive information
  const sanitizedRequest = { ...requestData };
  if (sanitizedRequest.messages) {
    // Redact or truncate message content if needed
    sanitizedRequest.messages = sanitizedRequest.messages.map(msg => ({
      ...msg,
      content: msg.content.length > 50 ? `${msg.content.substring(0, 50)}...` : msg.content
    }));
  }
  
  console.error('API Error:', {
    type: error.type,
    code: error.code,
    message: error.message,
    requestDetails: sanitizedRequest
  });
}

Error Response Format​

Error Properties​

HTTP Status Code Reference​

Authentication Errors (401)​

Unauthorized​

Unauthorized API Key​

Missing API Key​

Permission Errors (403)​

Forbidden​

Resource Errors (404)​

Model Not Found​

Rate Limiting Errors (429)​

Insufficient Quota​

Too Many Requests​

Request Validation Errors (400)​

Missing Required Parameters​

Missing Model Parameter​

Missing Model Parameter (Alternative)​

Missing Prompt Parameter​

Missing Input Parameter​

Message Structure Errors​

Invalid Role​

Missing Tool Calls in Assistant Role​

Missing Content in Non-Assistant Role​

Parameter Range Validation Errors​

Temperature Validation​

Frequency Penalty Validation​

Top Logprobs Validation​

Speed Validation (Text-to-Speech)​

N Parameter Validation​

Output Compression Validation (Text-to-Image)​

Logit Bias Validation Errors​

Invalid Logit Bias Key (Non-Integer)​

Invalid Logit Bias Key (Too Large)​

Invalid Logit Bias Value​

Enum Validation Errors​

Invalid Voice (Text-to-Speech)​

Invalid Modality Value​

Invalid Background Value (Text-to-Image)​

Invalid Moderation Value (Text-to-Image)​

Invalid Output Format (Text-to-Image)​

Invalid Size Value (Text-to-Image)​

Invalid Style Value (Text-to-Image)​

Server Errors (500)​

Internal Server Error​

Error Handling Best Practices​

Implement Retry Logic​

Gracefully Handle API Errors​

Log Errors Appropriately​

Error Response Format

Error Properties

HTTP Status Code Reference

Authentication Errors (401)

Unauthorized

Unauthorized API Key

Missing API Key

Permission Errors (403)

Forbidden

Resource Errors (404)

Model Not Found

Rate Limiting Errors (429)

Insufficient Quota

Too Many Requests

Request Validation Errors (400)

Missing Required Parameters

Missing Model Parameter

Missing Model Parameter (Alternative)

Missing Prompt Parameter

Missing Input Parameter

Message Structure Errors

Invalid Role

Missing Tool Calls in Assistant Role

Missing Content in Non-Assistant Role

Parameter Range Validation Errors

Temperature Validation

Frequency Penalty Validation

Top Logprobs Validation

Speed Validation (Text-to-Speech)

N Parameter Validation

Output Compression Validation (Text-to-Image)

Logit Bias Validation Errors

Invalid Logit Bias Key (Non-Integer)

Invalid Logit Bias Key (Too Large)

Invalid Logit Bias Value

Enum Validation Errors

Invalid Voice (Text-to-Speech)

Invalid Modality Value

Invalid Background Value (Text-to-Image)

Invalid Moderation Value (Text-to-Image)

Invalid Output Format (Text-to-Image)

Invalid Size Value (Text-to-Image)

Invalid Style Value (Text-to-Image)

Server Errors (500)

Internal Server Error

Error Handling Best Practices

Implement Retry Logic

Gracefully Handle API Errors

Log Errors Appropriately