错误码

TokenSupernova 使用标准 HTTP 状态码，并以 OpenAI 兼容格式返回错误信息。

错误响应格式

{
  "error": {
    "message": "提供的 API Key 无效",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

HTTP 状态码

状态码	含义	处理方式
200	成功	请求已处理
400	请求错误	检查请求体是否有误
401	未授权	API Key 缺失或无效
402	需要付款	账户余额不足 — 充值
404	未找到	模型或接口不存在
429	速率限制	降低请求频率
500	服务器错误	我们的问题 — 重试
503	服务不可用	模型临时过载 — 退避重试

常见错误

401 — API Key 无效

{
  "error": {
    "message": "提供的 API Key 无效。请在 api.tokensupernova.com/console 检查你的 Key。",
    "type": "auth_error",
    "code": "invalid_api_key"
  }
}

解决：确认 API Key 以 tsn_live_ 开头，且复制完整。

402 — 余额不足

{
  "error": {
    "message": "余额不足。请在 api.tokensupernova.com/console 充值。",
    "type": "billing_error",
    "code": "insufficient_balance"
  }
}

解决：在控制台中为账户充值。

429 — 速率限制

{
  "error": {
    "message": "超出速率限制。请在 60 秒后重试。",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

解决：实现指数退避重试。参见 速率限制 →

500 — 服务器错误

{
  "error": {
    "message": "服务器内部错误。请重试。",
    "type": "server_error",
    "code": "internal_error"
  }
}

解决：使用指数退避重试。如问题持续，联系支持。

重试策略

建议对 429 和 5xx 错误实现指数退避：

import time
import random

def retry_with_backoff(fn, max_retries=5, base_delay=1):
    for attempt in range(max_retries):
        try:
            return fn()
        except RateLimitError:
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)
    raise Exception("超过最大重试次数")