Skip to main content

Error Codes

This guide provides an overview of the error codes you might encounter when using the IG1 AI API. Each error includes the cause and recommended solutions.

API Errors Overview​

IG1 AI uses conventional HTTP response codes to indicate the success or failure of API requests:

  • 2xx codes indicate success
  • 4xx codes indicate an error with the request (authentication, parameters, rate limits, budget)
  • 5xx codes indicate an issue on our server side

All error responses include a JSON body with the following structure:

{
  "message": "Human-readable error message",
  "code": 400,
  "request_id": "req_abc123xyz"
}
tip

When contacting support about an error, always include the request_id to help us diagnose the issue quickly.

note

Endpoint paths: Most endpoints are under /v1/ (e.g., /v1/chat/completions, /v1/embeddings), but some are not:

  • /document - Document to markdown conversion
  • /usage - Current month usage summary
  • /usage/history - Detailed usage by model and day

Error Code Reference​

CodeMessageOverview
400 - Bad RequestVariousThe request was malformed or contains invalid parameters
401 - UnauthorizedUnauthorizedMissing or invalid API key
402 - Payment RequiredCommit exceededMonthly budget limit exceeded
403 - ForbiddenForbiddenAPI key does not exist or is inactive
500 - Internal Server ErrorInternal Server ErrorServer-side error during request processing
502 - Bad GatewayFailed to forward requestBackend model service unavailable

400 - Bad Request​

This error indicates that your request was malformed, contains invalid parameters, or references resources that don't exist.

Common Causes​

Invalid JSON payload​

  • Messages: "Request body processing error.", "Failed to parse request", "Bad JSON."
  • Cause: The request body is not valid JSON or doesn't match the expected schema
  • Solution: Check that your request body is properly formatted JSON. Validate against the API schema for the specific endpoint you're calling.

Unknown model​

  • Message: "Unknown model {model}"
  • Cause: The model name specified in your request doesn't exist in our catalog
  • Solution: Verify the model name. Check the Models overview page for the complete list of available models and their correct names.
note

For image models with prompt enhancing enabled, use the model name with the -pe suffix (e.g., flux-1-pe instead of flux-1). This automatically enables prompt enhancement using the configured LLM.

Invalid parameters​

  • Messages: "Unknown quality {quality}", "Invalid month parameter.", "Invalid year parameter."
  • Cause: A parameter value is outside the accepted range or format
  • Solution: Review the endpoint documentation for valid parameter values and formats.

Too many input images​

  • Message: "Model {model} only supports up to {N} input images"
  • Cause: You've provided more input images than the model supports
  • Solution: Reduce the number of input images to within the model's limits. Check the Image models documentation.

Invalid content type​

  • Message: "Invalid content type. Must be application/json or multipart/form-data."
  • Cause: The Content-Type header doesn't match the expected format
  • Solution: Use application/json for JSON payloads or multipart/form-data for file uploads.

Prompt enhancing not supported​

  • Message: "Prompt enhancing not supported for model {model}"
  • Cause: You're trying to use prompt enhancement with a model that doesn't support it
  • Solution: Check the model's capabilities in the Image models documentation.

401 - Unauthorized​

This error indicates that your request is missing valid authentication credentials.

Message: Unauthorized​

Cause:

  • The Authorization header is missing or empty
  • The header format is incorrect

Solution:

  1. Include the Authorization header in your request: 
    Authorization: Bearer YOUR_API_KEY
  2. Verify your API key is correctly formatted (no extra spaces or characters)
  3. Check your API key settings

402 - Payment Required​

Message: Commit exceeded: {totalCost} >= {maxCost}​

Cause: Your organization has exceeded its monthly budget limit (MaxCostPerMonth).

Solution:

  1. Check your current usage (see Usage API and Usage History)
  2. Contact your organization administrator to review budget settings
  3. Wait until the next billing cycle when usage resets

403 - Forbidden​

Message: Forbidden​

Cause: The API key provided doesn't exist in our database or has been deactivated.

Solution:

  1. Verify you're using the correct API key from your organization settings
  2. Ensure your API key hasn't been revoked or expired
  3. If you've recently created a new key, wait a few moments and try again
  4. Contact your organization administrator if you believe this is an error

500 - Internal Server Error​

This error indicates that something went wrong on our side while processing your request.

Common Messages​

MessageWhen it occurs
"Internal Server Error"Generic server error during request processing
"Failed to get model"Database error when looking up model information
"Failed to tokenize input."Error during text tokenization
"Input rate limiter error"Rate limiter service encountered an error
"Failed to marshal request payload"Error serializing the request
"Failed to decode backend response"Error parsing the model's response
"Failed to extract image data"Error processing image generation output
"Failed to convert image format"Error during image format conversion

Solution:

  1. Retry your request after a brief wait (we recommend exponential backoff)
  2. Include the request_id from the error response when contacting support
  3. Check our status page for any ongoing incidents
  4. If the issue persists, contact support with the request ID
note

All 5xx errors include the suffix: " Please contact the administrator with the request ID."

502 - Bad Gateway​

Message: Failed to forward request to backend​

Cause: The backend model service (vLLM or other inference engine) is temporarily unavailable.

Solution:

  1. Retry your request after a brief wait (typically resolves within seconds)
  2. Implement retry logic with exponential backoff in your application
  3. If the issue persists for more than a few minutes, contact support

Error Handling Best Practices​

Implement Retry Logic​

For transient errors (5xx codes), implement retry logic with exponential backoff:

import time
from openai import OpenAI, APIError

client = OpenAI(base_url="https://api.ig1.ai/v1", api_key="your-api-key")

def make_request_with_retry(max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="qwen35-397b-a17b-instruct-general",
                messages=[{"role": "user", "content": "Hello"}]
            )
            return response
        except APIError as e:
            if attempt == max_retries - 1:
                raise  # Last attempt, re-raise the error
            
            # Wait before retrying (exponential backoff)
            wait_time = 2 ** attempt
            print(f"Attempt {attempt + 1} failed. Retrying in {wait_time}s...")
            time.sleep(wait_time)

# Usage
try:
    response = make_request_with_retry()
    print(response.choices[0].message.content)
except APIError as e:
    print(f"Request failed after retries: {e}")

Log Request IDs​

Always log the request_id from error responses. This is crucial for debugging:

try:
    response = client.chat.completions.create(
        model="qwen35-397b-a17b-instruct-general",
        messages=[{"role": "user", "content": "Hello"}]
    )
except APIError as e:
    request_id = getattr(e, 'request_id', 'unknown')
    print(f"Error (request_id: {request_id}): {e}")
    # Log this to your monitoring system

Handle Specific Error Codes​

Differentiate between client errors (4xx) and server errors (5xx):

from openai import (
    BadRequestError,
    RateLimitError,
    APIConnectionError,
    InternalServerError,
    AuthenticationError
)

try:
    response = client.chat.completions.create(
        model="qwen35-397b-a17b-instruct-general",
        messages=[{"role": "user", "content": "Hello"}]
    )
except BadRequestError as e:
    # Don't retry - fix the request
    print(f"Invalid request: {e}")
except AuthenticationError as e:
    # Check your API key
    print(f"Authentication failed: {e}")
except RateLimitError as e:
    # Wait and retry
    print(f"Rate limited, waiting...")
except (APIConnectionError, InternalServerError) as e:
    # Retry with backoff
    print(f"Server error, will retry...")

Getting Help​

If you encounter persistent errors that you cannot resolve:

  1. Check the documentation: Review the specific endpoint documentation for parameter requirements
  2. Verify your setup: Ensure your Master API Key is correct and you're using the right base URL
  3. Retry the request: For 5xx errors, wait a moment and try again
  4. Contact support: Reach out with the following information:
    • The request_id from the error response
    • The endpoint you're calling
    • The model you're using
    • A sanitized version of your request (remove sensitive data)
    • A sanitized version of your request (remove sensitive data)
    • The timestamp of the error

Support Channels​

  • Documentation: Browse the API Reference for detailed endpoint documentation
  • Documentation: Browse the API Reference for detailed endpoint documentation
  • Models: Check the Models overview for available models and their capabilities

Quick Reference Table​

HTTP CodeRetry?Action Required
400❌ NoFix request parameters
401❌ NoUpdate API key
402❌ NoContact admin about budget
403❌ NoVerify API key is active
500✅ YesRetry with backoff
502✅ YesRetry with backoff
info

Note: All error messages from the IG1 AI API include a suffix: " Please contact the administrator with the request ID." This is intentional to help with debugging and support requests.