错误处理

了解 AIDESK API 返回的错误码及处理方式。

AIDESK API 使用标准 HTTP 状态码指示请求的成功或失败。当请求出错时，响应体中会包含 JSON 格式的错误详情，帮助你快速定位和解决问题。

错误响应格式

所有错误响应均返回 JSON 格式，包含以下字段：

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}
字段类型说明
error.messagestring人类可读的错误描述
error.typestring错误类型分类
error.codestring具体的错误代码，便于程序化处理

错误码一览

以下是常见的 HTTP 错误状态码及其含义：

常见原因

  • API 密钥拼写错误或包含多余空格
  • 密钥已过期或被撤销
  • 请求头中未包含 Authorization 字段

解决方案

  • 前往控制台确认 API 密钥是否正确
  • 检查请求头格式：Authorization: Bearer sk-aidesk-YOUR_KEY
  • 如果密钥已失效，生成新的 API 密钥

响应示例

{
  "error": {
    "message": "Invalid API key provided: sk-aidesk-***",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

常见原因

  • 账户余额不足
  • 请求的模型不在当前计划可用范围内
  • 账户因违规被暂停

解决方案

  • 检查账户余额并充值
  • 确认请求的模型在当前计划中可用
  • 联系支持团队了解账户状态

响应示例

{
  "error": {
    "message": "Insufficient permissions to access this model",
    "type": "permission_error",
    "code": "model_access_denied"
  }
}

常见原因

  • 短时间内发送过多请求
  • 并发请求数超过限制
  • 令牌桶配额耗尽

解决方案

  • 等待片刻后重试（响应头 Retry-After 会指示等待时间）
  • 在代码中实现指数退避重试策略
  • 降低请求频率，合理分配调用间隔
  • 如需更高的速率限制，考虑升级计划

响应示例

{
  "error": {
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

常见原因

  • 模型 ID 拼写错误或模型已下线
  • 请求的端点路径不正确

解决方案

  • 通过 /v1/models 接口确认模型 ID 是否正确
  • 检查请求 URL 是否准确

响应示例

{
  "error": {
    "message": "The model 'gpt-5' does not exist",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

常见原因

  • AIDESK 服务端临时故障
  • 上游模型提供商返回异常
  • 请求内容触发了未预期的服务端错误

解决方案

  • 稍后重试（通常为临时性问题）
  • 如果持续出现，检查请求内容是否异常
  • 联系支持团队并提供错误详情和请求 ID

响应示例

{
  "error": {
    "message": "An internal server error occurred. Please try again later.",
    "type": "server_error",
    "code": "internal_error"
  }
}

常见原因

  • 服务正在维护或部署中
  • 上游提供商暂时不可用

解决方案

  • 等待片刻后重试
  • 查看 AIDESK 状态页面了解服务状况

响应示例

{
  "error": {
    "message": "Service temporarily unavailable. Please try again later.",
    "type": "server_error",
    "code": "service_unavailable"
  }
}

处理建议

  • 客户端错误（4xx）需要检查并修改请求，服务端错误（5xx）可等待后重试
  • 对 429 错误使用指数退避重试，并读取 Retry-After 响应头设置等待时间
  • 将 error.code 和 error.message 记录到日志中便于排查

以下是一个使用指数退避策略处理 429 错误的 Python 示例：

import time
import requests

API_BASE = "https://api.aideskapp.com/v1"
API_KEY = "sk-aidesk-YOUR_KEY"

def chat_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            f"{API_BASE}/chat/completions",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={"model": "claude-sonnet-4-6", "messages": messages},
        )

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

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
            print(f"Rate limited. Retrying in {retry_after}s...")
            time.sleep(retry_after)
            continue

        # Non-retryable error
        raise Exception(f"API error: {response.status_code} - {response.text}")

    raise Exception("Max retries exceeded")