错误码查询

本文档列出了 AIX Gateway API 可能返回的所有错误码及其含义。当 API 请求失败时，响应中会包含具体的错误码，帮助您快速定位问题。

INFO

如需反馈问题，请提供 Header 中的 X-Request-Id，以便我们为您排查。

错误响应格式

json

{
  "error": {
    "message": "错误的详细描述",
    "type": "错误类型",
    "code": "错误码"
  }
}

HTTP 状态码

所有错误响应都会返回对应的 HTTP 状态码：

4xx: 客户端错误（请求格式、参数、认证等问题）
5xx: 服务端错误（服务故障、上游服务异常等）

错误码分类

认证与授权错误

错误码	HTTP 状态码	说明	解决方案
`invalid_api_key`	401	API Key 无效或已过期	检查 API Key 是否正确，或联系管理员获取新的密钥
`authentication_error`	401	认证失败	确认请求头中包含正确的 `Authorization` 字段
`permission_denied`	403	权限不足	您的账户没有权限访问此资源，请联系管理员

配额与限流错误

错误码	HTTP 状态码	说明	解决方案
`insufficient_quota`	403	配额不足	您的账户余额或配额已用尽，请充值或升级套餐
`rate_limit_exceeded`	429	超出速率限制	请求频率过高，请稍后重试或联系管理员提升限额
`too_many_requests`	429	请求过多	短时间内请求次数过多，请降低请求频率
`billing_quota_exceeded`	403	计费配额超限	您的使用量已达到配额上限

请求错误

错误码	HTTP 状态码	说明	解决方案
`invalid_request_error`	400	请求参数无效	检查请求参数是否符合 API 文档要求
`request_parse_failed`	400	请求解析失败	确认请求体是有效的 JSON 格式
`request_validation_failed`	400	请求验证失败	检查必填参数是否缺失，参数类型是否正确
`unprocessable_entity`	422	无法处理的请求	请求格式正确但内容无法处理，请检查参数值
`request_timeout`	408	请求超时	服务器未在规定时间内收到完整请求，请检查网络连接

资源错误

错误码	HTTP 状态码	说明	解决方案
`not_found_error`	404	资源不存在	请求的资源（模型、任务等）不存在，请检查资源 ID
`task_not_found`	404	任务不存在	请求的任务 ID 不存在或已过期
`conflict_error`	409	资源冲突	请求的操作与当前资源状态冲突

模型与功能错误

错误码	HTTP 状态码	说明	解决方案
`channel_model_mapping_failed`	400	模型不可用	请求的模型当前不可用，请尝试其他模型
`feature_not_supported`	501	功能不支持	当前模型或渠道不支持此功能（如 `stream_options`）

内容审核错误

错误码	HTTP 状态码	说明	解决方案
`sensitive_words_detected`	403	检测到敏感词	您的请求包含敏感内容，请修改后重试
`moderation_blocked`	403	内容被审核拦截	请求内容违反内容政策，无法处理
`text_moderation_failed`	403	文本审核失败	文本内容未通过审核

服务与上游错误

错误码	HTTP 状态码	说明	解决方案
`internal_server_error`	500	内部服务器错误	服务器遇到意外错误，请稍后重试或联系技术支持
`service_unavailable`	503	服务不可用	服务暂时不可用，通常是维护或高负载，请稍后重试
`engine_overloaded`	503	引擎过载	AI 引擎负载过高，请稍后重试
`upstream_error`	502	上游服务错误	上游 AI 服务返回错误，请稍后重试
`upstream_timeout`	504	上游服务超时	上游 AI 服务响应超时，请稍后重试
`upstream_unavailable`	503	上游服务不可用	上游 AI 服务暂时不可用

异步任务错误

用于异步任务场景的错误码：

错误码	HTTP 状态码	说明	解决方案
`task_not_found`	404	任务不存在	任务 ID 不存在或已过期，请检查任务 ID
`task_execution_failed`	500	任务执行失败	任务创建或执行失败，请查看错误详情
`task_fetch_failed`	500	任务状态获取失败	无法获取任务状态，请稍后重试

常见问题

1. 收到 401 错误怎么办？

原因: API Key 无效、过期或格式错误

解决方案:

检查请求头是否包含 Authorization: Bearer YOUR_API_KEY
确认 API Key 是否正确（复制粘贴时可能有空格）
检查 API Key 是否已过期或被禁用
联系管理员获取新的 API Key

2. 收到 403 错误怎么办？

原因: 配额不足、权限不足或内容违规

解决方案:

配额不足（insufficient_quota）: 充值或升级套餐
速率限制（rate_limit_exceeded）: 降低请求频率
敏感词（sensitive_words_detected）: 修改请求内容
权限不足（permission_denied）: 联系管理员开通权限

3. 收到 429 错误怎么办？

原因: 请求频率过高

解决方案:

降低请求频率（建议实现指数退避重试）
检查是否有多个客户端使用同一 API Key
联系管理员提升速率限制

4. 收到 500 / 502 / 503 错误怎么办？

原因: 服务端临时故障

解决方案:

等待 1-5 分钟后重试
实现自动重试机制（建议 3 次，间隔递增）
如果持续失败超过 30 分钟，联系技术支持

5. 流式请求中断怎么办？

可能的错误码:

stream_closed: 连接被上游关闭
stream_timeout: 流式处理超时
stream_parse_failed: 数据格式错误

解决方案:

检查网络连接是否稳定
增加客户端超时时间
重新发起请求

重试策略建议

应该重试的错误

以下错误通常是临时性的，建议实现自动重试：

HTTP 状态码	错误场景	重试策略
408	请求超时	立即重试，最多 3 次
429	速率限制	等待后重试（指数退避：1s, 2s, 4s）
500	内部错误	等待后重试（1s, 3s, 5s）
502	上游错误	等待后重试（1s, 3s, 5s）
503	服务不可用	等待后重试（2s, 5s, 10s）
504	网关超时	等待后重试（2s, 5s, 10s）

不应重试的错误

以下错误是确定性的，重试无效：

HTTP 状态码	错误场景
400	请求参数错误
401	认证失败
403	权限不足 / 配额用尽
404	资源不存在
422	请求无法处理

重试示例代码

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)

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

            # 不应重试的错误
            if response.status_code in [400, 401, 403, 404, 422]:
                return response.json()

            # 速率限制
            if response.status_code == 429:
                wait_time = 2 ** attempt  # 指数退避
                print(f"Rate limited, waiting {wait_time}s...")
                time.sleep(wait_time)
                continue

            # 服务端错误
            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()

      // 成功
      if (response.ok) {
        return data
      }

      // 不应重试的错误
      if ([400, 401, 403, 404, 422].includes(response.status)) {
        return data
      }

      // 速率限制
      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
      }

      // 服务端错误
      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
    }
  }
}

错误排查步骤

步骤 1: 确认错误码

查看响应中的 error.code 字段，在本文档中查找对应的错误说明。

步骤 2: 检查 HTTP 状态码

4xx: 通常是客户端问题，检查请求参数、认证信息
5xx: 通常是服务端问题，可以重试

步骤 3: 阅读错误消息

error.message 包含详细的错误描述，通常能提供更多上下文信息。

步骤 4: 根据分类解决

认证问题: 检查 API Key
参数问题: 对照 API 文档检查参数
配额问题: 检查账户余额
服务问题: 稍后重试或联系技术支持

技术支持

如果您遇到以下情况，请联系技术支持：

错误持续超过 30 分钟
错误消息不清晰或与文档不符
怀疑服务故障
需要提升配额或速率限制

附录

错误码速查表

按 HTTP 状态码分类：

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 格式

官方格式

OpenAI 格式

官方格式

OpenAI 格式

OpenAI 格式

OpenAI 格式

OpenAI 格式

错误码查询

错误响应格式

HTTP 状态码

错误码分类

认证与授权错误

配额与限流错误

请求错误

资源错误

模型与功能错误

内容审核错误

服务与上游错误

异步任务错误

常见问题

1. 收到 401 错误怎么办？

2. 收到 403 错误怎么办？

3. 收到 429 错误怎么办？

4. 收到 500 / 502 / 503 错误怎么办？

5. 流式请求中断怎么办？

重试策略建议

应该重试的错误

不应重试的错误

重试示例代码

错误排查步骤

步骤 1: 确认错误码

步骤 2: 检查 HTTP 状态码

步骤 3: 阅读错误消息

步骤 4: 根据分类解决

技术支持

附录

错误码速查表

错误码查询 ​

错误响应格式 ​

HTTP 状态码 ​

错误码分类 ​

认证与授权错误 ​

配额与限流错误 ​

请求错误 ​

资源错误 ​

模型与功能错误 ​

内容审核错误 ​

服务与上游错误 ​

异步任务错误 ​

常见问题 ​

1. 收到 401 错误怎么办？ ​

2. 收到 403 错误怎么办？ ​

3. 收到 429 错误怎么办？ ​

4. 收到 500 / 502 / 503 错误怎么办？ ​

5. 流式请求中断怎么办？ ​

重试策略建议 ​

应该重试的错误 ​

不应重试的错误 ​

重试示例代码 ​

错误排查步骤 ​

步骤 1: 确认错误码 ​

步骤 2: 检查 HTTP 状态码 ​

步骤 3: 阅读错误消息 ​

步骤 4: 根据分类解决 ​

技术支持 ​

附录 ​

错误码速查表 ​

错误码查询

错误响应格式

HTTP 状态码

错误码分类

认证与授权错误

配额与限流错误

请求错误

资源错误

模型与功能错误

内容审核错误

服务与上游错误

异步任务错误

常见问题

1. 收到 401 错误怎么办？

2. 收到 403 错误怎么办？

3. 收到 429 错误怎么办？

4. 收到 500 / 502 / 503 错误怎么办？

5. 流式请求中断怎么办？

重试策略建议

应该重试的错误

不应重试的错误

重试示例代码

错误排查步骤

步骤 1: 确认错误码

步骤 2: 检查 HTTP 状态码

步骤 3: 阅读错误消息

步骤 4: 根据分类解决

技术支持

附录

错误码速查表