跳转到主要内容
AIsa API 的响应遵循标准 HTTP 语义：成功调用返回 2xx，客户端错误返回 4xx，服务端或上游错误返回 5xx。本页说明错误模型以及不同错误的处理方式。

​
错误响应结构

错误响应始终是包含 error 对象的 JSON： 
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "request_id": "req_01JABCD9F1YYEXAMPLE"
  }
}
字段含义
type高层错误类别，例如 authentication_error、invalid_request_error、rate_limit_error、api_error、upstream_error
code机器可读的稳定错误代码，可安全用于程序匹配
message供人阅读的错误说明
request_id请求的唯一 ID。提交支持工单时请附上该值。

​
状态码

请求 Payload 格式错误，例如缺少必填参数、类型错误、JSON 无效或参数值超出范围。常见代码： invalid_request、missing_parameter、invalid_parameter_type、json_parse_error处理方式： 修正请求后再试，不要自动重试。
未提供 API Key、Authorization 请求头格式错误，或密钥无效/已撤销。常见代码： missing_api_key、invalid_api_key、revoked_api_key处理方式： 在控制台中检查密钥，并使用 Authorization: Bearer YOUR_A...EY 重新发送请求。
密钥有效，但无权访问该端点、模型或区域。常见代码： insufficient_permissions、model_not_allowed、region_blocked处理方式： 检查工作区套餐和密钥权限范围。如果限制不符合预期，请联系支持团队。
端点路径、模型 ID 或资源 ID 不存在。常见代码： unknown_model、resource_not_found、unknown_endpoint处理方式： 对照模型目录检查模型名，并对照 API 参考检查端点路径。
语法有效，但请求违反业务规则，例如 max_tokens 超过模型限制、参数组合不受支持，或内容违反上游提供商的安全策略。常见代码： max_tokens_exceeded、unsupported_parameter、content_policy_violation处理方式： 仔细阅读 message 并调整 Payload，不要盲目重试。
请求触发了速率限制，可能是账户 RPM/TPM 上限，也可能是上游提供商的限流。常见代码： rate_limit_exceeded、upstream_rate_limit、quota_exceeded返回的响应头：
  • Retry-After：允许再次尝试前需要等待的秒数
  • X-RateLimit-Limit：当前限制
  • X-RateLimit-Remaining：当前窗口中的剩余请求数
  • X-RateLimit-Reset：计数器重置时的 UNIX 时间戳
处理方式： 退避后重试，具体方式见下方重试指南。完整额度表请参阅速率限制。
AIsa 侧发生意外错误。request_id 字段对于支持团队排查问题非常重要。处理方式： 使用指数退避重试。如果错误持续出现，请将 request_id 发送至 developer@aisa.one。
AIsa 无法连接上游模型提供商（例如 OpenAI、Anthropic），或从上游收到错误。此类问题通常是暂时的。常见代码： upstream_unavailable、upstream_timeout、gateway_error处理方式： 使用指数退避重试。如果问题持续出现，请切换备用模型；网关可以通过不同上游部署路由 Claude 请求。

​
重试指南

1

只重试幂等或可安全重复的调用

所有 GET 请求和大多数聊天补全调用都可以安全重试。不要盲目重试会产生副作用的 POST 请求，例如发布推文。
2

遵守 `Retry-After`

收到 429 响应时，始终遵守 Retry-After 响应头。收到未包含该响应头的 5xx 错误时，使用指数退避。
3

使用带抖动的指数退避

从 1 秒开始，每次尝试将等待时间翻倍，并添加 ±25% 抖动，上限为 30 秒。
1.0s → 2.0s → 4.0s → 8.0s → 16.0s → 30.0s (max)
4

限制总重试时间

尝试 3–5 次或总计 60 秒后停止，以先到者为准，并将错误返回给调用方。
5

除 429 外，不要重试 4xx

400、401、403、404 和 422 表示请求本身存在问题，重试无法解决。

​
最小重试示例（Python）

import time, random
from openai import OpenAI, APIError, RateLimitError

client = OpenAI(base_url="https://api.aisa.one/v1", api_key="sk-aisa-...")

def call_with_retry(messages, model="gpt-5", max_retries=5):
    delay = 1.0
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(model=model, messages=messages)
        except RateLimitError as e:
            wait = getattr(e.response.headers, "Retry-After", None) or delay
            time.sleep(float(wait) * (1 + random.uniform(-0.25, 0.25)))
        except APIError as e:
            if e.status_code >= 500:
                time.sleep(delay * (1 + random.uniform(-0.25, 0.25)))
            else:
                raise
        delay = min(delay * 2, 30)
    raise RuntimeError("Exceeded max retries")

​
获取帮助

向 developer@aisa.one 报告问题时，请提供：
  • 错误响应中的 request_id
  • HTTP 状态码和 error.code
  • 模型 ID 和最小复现示例（使用已脱敏密钥的 cURL）
  • 请求失败的大致时间