Error codes

This document lists error codes that the AIX Gateway API may return and what they mean. When a request fails, the response includes a specific error code to help you locate the issue quickly.

INFO

When reporting an issue, please include the X-Request-Id from the response headers so we can investigate.

Error response format

json

{
  "error": {
    "message": "Detailed error description",
    "type": "Error type",
    "code": "Error code"
  }
}

HTTP status codes

All error responses return a corresponding HTTP status code:

4xx: Client errors (request format, parameters, authentication, etc.)
5xx: Server errors (service faults, upstream failures, etc.)

Error code categories

Authentication and authorization errors

Error code	HTTP status	Description	Resolution
`invalid_api_key`	401	API Key is invalid or expired	Check that the API Key is correct, or contact an admin for a new key
`authentication_error`	401	Authentication failed	Confirm the request includes a valid `Authorization` header
`permission_denied`	403	Insufficient permissions	Your account cannot access this resource; contact an admin

Quota and rate-limit errors

Error code	HTTP status	Description	Resolution
`insufficient_quota`	403	Insufficient quota	Your account balance or quota is exhausted; top up or upgrade your plan
`rate_limit_exceeded`	429	Rate limit exceeded	Request rate is too high; retry later or ask an admin to raise the limit
`too_many_requests`	429	Too many requests	Too many requests in a short period; reduce request frequency
`billing_quota_exceeded`	403	Billing quota exceeded	Your usage has reached the quota limit

Request errors

Error code	HTTP status	Description	Resolution
`invalid_request_error`	400	Invalid parameters are invalid	Check that parameters match the API documentation
`request_parse_failed`	400	Failed to parse the request	Confirm the request body is valid JSON
`request_validation_failed`	400	Request validation failed	Check for missing required parameters or incorrect types
`unprocessable_entity`	422	Unprocessable request	Format is valid but content cannot be processed; check parameter values
`request_timeout`	408	Request timed out	The server did not receive the full request in time; check your network

Resource errors

Error code	HTTP status	Description	Resolution
`not_found_error`	404	Resource not found	The requested resource (model, task, etc.) does not exist; check the resource ID
`task_not_found`	404	Task not found	The requested task ID does not exist or has expired
`conflict_error`	409	Resource conflict	The operation conflicts with the current resource state

Model and feature errors

Error code	HTTP status	Description	Resolution
`channel_model_mapping_failed`	400	Model unavailable	The requested model is currently unavailable; try another model
`feature_not_supported`	501	Feature not supported	The current model or channel does not support this feature (e.g. `stream_options`)

Content moderation errors

Error code	HTTP status	Description	Resolution
`sensitive_words_detected`	403	Sensitive words detected	Your request contains sensitive content; modify and retry
`moderation_blocked`	403	Content blocked by moderation	The request violates content policy and cannot be processed
`text_moderation_failed`	403	Text moderation failed	The text content did not pass moderation

Service and upstream errors

Error code	HTTP status	Description	Resolution
`internal_server_error`	500	Internal server error	The server hit an unexpected error; retry later or contact support
`service_unavailable`	503	Service unavailable	Service is temporarily unavailable (maintenance or high load); retry later
`engine_overloaded`	503	Engine overloaded	The AI engine is under heavy load; retry later
`upstream_error`	502	Upstream service error	The upstream AI service returned an error; retry later
`upstream_timeout`	504	Upstream service timeout	The upstream AI service timed out; retry later
`upstream_unavailable`	503	Upstream service unavailable	The upstream AI service is temporarily unavailable

Async task errors

Error codes used in async task scenarios:

Error code	HTTP status	Description	Resolution
`task_not_found`	404	Task not found	The task ID does not exist or has expired; check the task ID
`task_execution_failed`	500	Task execution failed	Task creation or execution failed; see error details
`task_fetch_failed`	500	Failed to fetch task status	Unable to get task status; retry later

FAQ

1. What should I do if I get a 401 error?

Cause: Invalid, expired, or malformed API Key

Resolution:

Check that the request header includes Authorization: Bearer YOUR_API_KEY
Confirm the API Key is correct (extra spaces can be introduced when copying)
Check whether the API Key has expired or been disabled
Contact an admin for a new API Key

2. What should I do if I get a 403 error?

Cause: Insufficient quota, insufficient permissions, or content policy violation

Resolution:

Insufficient quota (insufficient_quota): Top up or upgrade your plan
Rate limit (rate_limit_exceeded): Reduce request frequency
Sensitive words (sensitive_words_detected): Modify the request content
Insufficient permissions (permission_denied): Contact an admin to enable access

3. What should I do if I get a 429 error?

Cause: Request rate is too high

Resolution:

Reduce request frequency (recommend exponential backoff retries)
Check whether multiple clients share the same API Key
Contact an admin to raise the rate limit

4. What should I do if I get a 500 / 502 / 503 error?

Cause: Temporary server-side failure

Resolution:

Wait 1–5 minutes and retry
Implement automatic retries (recommend 3 attempts with increasing intervals)
If failures persist for more than 30 minutes, contact technical support

5. What should I do if a streaming request is interrupted?

Possible error codes:

stream_closed: Connection closed by upstream
stream_timeout: Streaming processing timed out
stream_parse_failed: Data format error

Resolution:

Check that the network connection is stable
Increase the client timeout
Resubmit the request

Retry strategy recommendations

Errors that should be retried

These errors are usually transient; implement automatic retries:

HTTP status	Scenario	Retry strategy
408	Request timeout	Retry immediately, up to 3 times
429	Rate limit	Wait then retry (exponential backoff: 1s, 2s, 4s)
500	Internal error	Wait then retry (1s, 3s, 5s)
502	Upstream error	Wait then retry (1s, 3s, 5s)
503	Service unavailable	Wait then retry (2s, 5s, 10s)
504	Gateway timeout	Wait then retry (2s, 5s, 10s)

Errors that should not be retried

These errors are deterministic; retries will not help:

HTTP status	Scenario
400	Invalid parameter error
401	Authentication failed
403	Insufficient permissions / quota exhausted
404	Resource not found
422	Request cannot be processed

Retry example code

PythonNode.js

python

import time
import requests

def call_api_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=data, timeout=30)

            # Success
            if response.status_code == 200:
                return response.json()

            # Do not retry
            if response.status_code in [400, 401, 403, 404, 422]:
                return response.json()

            # Rate limited
            if response.status_code == 429:
                wait_time = 2 ** attempt  # exponential backoff
                print(f"Rate limited, waiting {wait_time}s...")
                time.sleep(wait_time)
                continue

            # Server error
            if response.status_code >= 500:
                if attempt < max_retries - 1:
                    wait_time = (attempt + 1) * 2
                    print(f"Server error, retrying in {wait_time}s...")
                    time.sleep(wait_time)
                    continue

        except requests.exceptions.Timeout:
            if attempt < max_retries - 1:
                print("Timeout, retrying...")
                time.sleep(1)
                continue

        except requests.exceptions.RequestException as e:
            print(f"Request failed: {e}")
            break

    return None

async function callApiWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options)
      const data = await response.json()

      // Success
      if (response.ok) {
        return data
      }

      // Do not retry
      if ([400, 401, 403, 404, 422].includes(response.status)) {
        return data
      }

      // Rate limited
      if (response.status === 429) {
        const waitTime = Math.pow(2, attempt) * 1000
        console.log(`Rate limited, waiting ${waitTime}ms...`)
        await new Promise((resolve) => setTimeout(resolve, waitTime))
        continue
      }

      // Server error
      if (response.status >= 500 && attempt < maxRetries - 1) {
        const waitTime = (attempt + 1) * 2000
        console.log(`Server error, retrying in ${waitTime}ms...`)
        await new Promise((resolve) => setTimeout(resolve, waitTime))
        continue
      }

      return data
    } catch (error) {
      if (attempt < maxRetries - 1) {
        console.log('Request failed, retrying...')
        await new Promise((resolve) => setTimeout(resolve, 1000))
        continue
      }
      throw error
    }
  }
}

Troubleshooting steps

Step 1: Confirm the error code

Check the error.code field in the response and look it up in this document.

Step 2: Check the HTTP status code

4xx: Usually a client issue; check request parameters and authentication
5xx: Usually a server issue; you can retry

Step 3: Read the error message

error.message contains a detailed description and often provides more context.

Step 4: Resolve by category

Auth issues: Check the API Key
Parameter issues: Compare parameters against the API docs
Quota issues: Check account balance
Service issues: Retry later or contact technical support

Technical support

Contact technical support if:

The error persists for more than 30 minutes
The error message is unclear or does not match the docs
You suspect a service outage
You need a higher quota or rate limit

Appendix

Error code quick reference

Grouped by HTTP status code:

400 Bad Request

invalid_request_error
request_parse_failed
request_validation_failed
channel_model_mapping_failed

401 Unauthorized

invalid_api_key
authentication_error

403 Forbidden

insufficient_quota
permission_denied
sensitive_words_detected
moderation_blocked
billing_quota_exceeded

404 Not Found

not_found_error
task_not_found

408 Request Timeout

request_timeout

429 Too Many Requests

rate_limit_exceeded
too_many_requests

500 Internal Server Error

internal_server_error
task_execution_failed
task_fetch_failed

502 Bad Gateway

upstream_error

503 Service Unavailable

service_unavailable
engine_overloaded
upstream_unavailable

504 Gateway Timeout

upstream_timeout
stream_timeout

OpenAI Format

Official Format

OpenAI Format

Official Format

OpenAI Format

OpenAI Format

OpenAI Format

OpenAI Format

Error codes

Error response format

HTTP status codes

Error code categories

Authentication and authorization errors

Quota and rate-limit errors

Request errors

Resource errors

Model and feature errors

Content moderation errors

Service and upstream errors

Async task errors

FAQ

1. What should I do if I get a 401 error?

2. What should I do if I get a 403 error?

3. What should I do if I get a 429 error?

4. What should I do if I get a 500 / 502 / 503 error?

5. What should I do if a streaming request is interrupted?

Retry strategy recommendations

Errors that should be retried

Errors that should not be retried

Retry example code

Troubleshooting steps

Step 1: Confirm the error code

Step 2: Check the HTTP status code

Step 3: Read the error message

Step 4: Resolve by category

Technical support

Appendix

Error code quick reference

Error codes ​

Error response format ​

HTTP status codes ​

Error code categories ​

Authentication and authorization errors ​

Quota and rate-limit errors ​

Request errors ​

Resource errors ​

Model and feature errors ​

Content moderation errors ​

Service and upstream errors ​

Async task errors ​

FAQ ​

1. What should I do if I get a 401 error? ​

2. What should I do if I get a 403 error? ​

3. What should I do if I get a 429 error? ​

4. What should I do if I get a 500 / 502 / 503 error? ​

5. What should I do if a streaming request is interrupted? ​

Retry strategy recommendations ​

Errors that should be retried ​

Errors that should not be retried ​

Retry example code ​

Troubleshooting steps ​

Step 1: Confirm the error code ​

Step 2: Check the HTTP status code ​

Step 3: Read the error message ​

Step 4: Resolve by category ​

Technical support ​

Appendix ​

Error code quick reference ​

Error codes

Error response format

HTTP status codes

Error code categories

Authentication and authorization errors

Quota and rate-limit errors

Request errors

Resource errors

Model and feature errors

Content moderation errors

Service and upstream errors

Async task errors

FAQ

1. What should I do if I get a 401 error?

2. What should I do if I get a 403 error?

3. What should I do if I get a 429 error?

4. What should I do if I get a 500 / 502 / 503 error?

5. What should I do if a streaming request is interrupted?

Retry strategy recommendations

Errors that should be retried

Errors that should not be retried

Retry example code

Troubleshooting steps

Step 1: Confirm the error code

Step 2: Check the HTTP status code

Step 3: Read the error message

Step 4: Resolve by category

Technical support

Appendix

Error code quick reference