错误处理 · Token360

Token360 使用 HTTP 状态码和兼容 OpenAI 的错误对象，便于应用以一致的方式处理请求失败。

本指南适用于兼容 OpenAI 的接口。如果某个接口页面说明了不同的响应信封或协议专用错误格式，请以该接口文档为准。

错误响应格式

JSON

1{
2  "code": "400",
3  "error": {
4    "message": "Missing required field: model",
5    "type": "invalid_request_error",
6    "param": "model",
7    "code": "invalid_request",
8    "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
9  },
10  "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
11}

请以 HTTP 响应状态作为判断成功或失败的首要依据，不要根据面向用户的 message 文本推断处理逻辑。

字段说明


`code`	string	字符串形式的 HTTP 状态码。
`error.message`	string	用于日志记录或展示的易读错误描述，具体文案可能调整。
`error.type`	string	错误的大类。
`error.param`	string，可选	与错误相关的请求参数（如有）。
`error.code`	string，可选	适合用于应用处理逻辑的机器可读语义码。
`traceId`	string	请求关联 ID，联系技术支持时请提供。
`error.traceId`	string	兼容 OpenAI 的错误对象中相同的请求关联 ID。
`serviceCode`	string，可选	Token360 的附加诊断码。该字段出现时，也可能同时位于 `error.serviceCode`；请在日志和支持请求中保留。

响应可能包含特定接口的附加字段。客户端应忽略无法识别的字段。

错误类型

error.type 表示错误大类，error.code 表示更具体的原因。


`invalid_request_error`	请求、参数或凭证无效。
`authentication_error`	身份认证失败或凭证无法使用。
`permission_error`	凭证有效，但无权访问请求的资源。
`not_found_error`	请求的资源不存在。
`rate_limit_error`	请求超过适用的速率或容量限制。
`insufficient_quota`	账户或 API Key 的余额或配额不足。
`api_error`	由于临时服务错误，当前无法完成请求。
`server_error`	Token360 遇到非预期服务端错误。

部分接口可能返回其文档中说明的其他类型。

常见错误码

同一种错误类型可能对应多个语义码。下表列出常见值，并非完整清单。


`invalid_request`	请求无效。	修正请求后再试。
`invalid_api_key`	API Key 缺失、无效或当前不可用。	检查凭证和认证请求头。
`model_not_found`	当前调用方无法使用请求的模型。	检查模型名称和访问权限。
`insufficient_permissions`	调用方缺少必要权限。	使用具备所需权限的凭证。
`rate_limit_exceeded`	达到速率或容量限制。	退避后重试。
`insufficient_quota`	可用余额或配额不足。	增加余额或配额，或使用其他符合条件的 API Key。
`request_too_large`	请求体超过允许大小。	减小请求体。
`unsupported_feature`	不支持请求的操作。	移除不支持的选项或改用受支持的操作。
`stream_interrupted`	流式响应因错误而结束。	将本次流视为失败，仅在操作可安全重试时重试。
`server_error`	发生临时或非预期服务错误。	如果操作可安全重复，请退避后重试。

HTTP 状态码


`400`	Bad Request	修正无效 JSON、参数或必填字段。
`401`	Unauthorized	检查 API Key 和 `Authorization: Bearer ...` 请求头。
`402`	Payment Required	补充足够的账户余额后再试。
`403`	Forbidden	检查 API Key 状态以及模型或资源访问权限。
`404`	Not Found	检查资源 ID 或模型名称。
`405`	Method Not Allowed	使用接口文档中指定的 HTTP 方法。
`409`	Conflict	解决请求状态冲突后再试。
`413`	Content Too Large	减小请求体或上传内容大小。
`429`	Too Many Requests	检查 `error.code`；`rate_limit_exceeded` 应退避重试，`insufficient_quota` 则需先解决配额问题。
`500`	Internal Server Error	如果操作可安全重复，请退避后重试。
`501`	Not Implemented	改用受支持的操作。
`502`	Bad Gateway	如果操作可安全重复，请退避后重试。
`503`	Service Unavailable	如果操作可安全重复，请退避后重试。
`504`	Gateway Timeout	如果操作可安全重复，请退避后重试。

常见示例

API Key 无效

JSON

1{
2  "code": "401",
3  "error": {
4    "message": "Invalid API key or token provided",
5    "type": "invalid_request_error",
6    "code": "invalid_api_key",
7    "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
8  },
9  "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
10}

请检查 API Key，并通过 Authorization: Bearer sk-your-api-key 发送。在修正凭证前不要重试。

余额或配额不足

JSON

1{
2  "code": "402",
3  "error": {
4    "message": "Insufficient account balance. Please recharge",
5    "type": "insufficient_quota",
6    "code": "insufficient_quota",
7    "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
8  },
9  "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
10}

请先增加足够的余额或配额。与配额有关的 429 也需要先解决配额问题，而不是持续重试。

超过速率限制

JSON

1{
2  "code": "429",
3  "error": {
4    "message": "Rate limit exceeded. Please slow down your requests",
5    "type": "rate_limit_error",
6    "code": "rate_limit_exceeded",
7    "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
8  },
9  "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
10}

请使用带随机抖动的指数退避策略重试。如果响应包含 Retry-After 请求头，请遵循该值。

临时服务错误

JSON

1{
2  "code": "503",
3  "error": {
4    "message": "Service temporarily unavailable",
5    "type": "api_error",
6    "code": "server_error",
7    "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
8  },
9  "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
10}

如果操作可安全重复，请使用指数退避策略重试。如果错误持续出现，请联系技术支持并提供关联 ID。

重试建议

对临时的 429、500、502、503 和 504 响应使用带随机抖动的指数退避策略。
如果 429 响应的 error.code 为 insufficient_quota，不要自动重试。
对 400、401、402、403、404、405、409、413 或 501 响应，在修正对应问题前不要自动重试。
设置最大重试次数和总时间限制。
仅重试可安全重复的操作。创建或提交类操作请遵循具体接口的幂等性说明。

请求 ID 与技术支持

除响应体中的 traceId 外，响应还可能包含 X-Request-Id 和 X-Trace-ID 请求头。请记录这些值以及 HTTP 状态、error.type、error.code 和可选的 serviceCode。不要记录 API Key、认证请求头或敏感请求内容。

使用 OpenAI Python SDK 处理错误

OpenAI Python SDK 会将 HTTP 错误映射为不同的异常类型：

Python

1from openai import (
2    APIConnectionError,
3    APIStatusError,
4    APITimeoutError,
5    AuthenticationError,
6    BadRequestError,
7    NotFoundError,
8    OpenAI,
9    PermissionDeniedError,
10    RateLimitError,
11)
12
13client = OpenAI(
14    api_key="sk-your-api-key",
15    base_url="https://api.token360.ai/v1",
16)
17
18try:
19    response = client.chat.completions.create(
20        model="claude-opus-5",
21        messages=[{"role": "user", "content": "Hello"}],
22    )
23except BadRequestError as exc:
24    print(f"Invalid request: {exc}")
25except AuthenticationError as exc:
26    print(f"Authentication failed: {exc}")
27except PermissionDeniedError as exc:
28    print(f"Permission denied: {exc}")
29except NotFoundError as exc:
30    print(f"Not found: {exc}")
31except RateLimitError as exc:
32    print(f"Rate limited; request_id={exc.request_id}")
33except (APITimeoutError, APIConnectionError) as exc:
34    print(f"Connection failed: {exc}")
35except APIStatusError as exc:
36    print(f"API error {exc.status_code}; request_id={exc.request_id}")

重试 RateLimitError 前，请检查响应体中的 error.code：对 rate_limit_exceeded 使用退避策略重试；如果是 insufficient_quota，请先解决配额问题。