错误代码

HTTP	说明
400	错误请求 - 您的请求无效。
401	未授权 - 您的 API 密钥错误。
403	当前用户或项目无权执行此请求。
402	ZeroClave 账户或项目额度不足，请检查套餐与额度。
404	未找到 - 请求的资源不存在。
413	请求正文超过允许大小，请缩小请求。
429	触发 ZeroClave 调用方限流；请降低频率并遵循可用的 Retry-After。
500	服务内部异常（internal_error），请稍后重试。
502	模型暂时不可用（model_unavailable），本次调用未能正常完成。
503	请检查 error.code：model_unavailable 表示模型暂时不可用；pii_mapping_saturated 表示隐私保护处理容量已满，需要管理员或平台支持协助。
504	模型调用超时（model_unavailable），请检查结果后再决定重试。

{"error":{"message":"模型暂时不可用，请稍后重试","type":"server_error","code":"model_unavailable"}}

隐私保护处理容量已满

收到 HTTP 503、error.type: "server_error" 且 error.code: "pii_mapping_saturated" 时，应停止自动重试，并携带响应头中的 X-Request-ID 联系项目管理员或平台支持。重复提交通常无法解决此问题，不能仅凭 HTTP 503 判断可以重试。

{"error":{"message":"当前隐私保护处理容量达到上限，请联系项目管理员或平台支持并提供请求编号；重复提交通常无效。","type":"server_error","code":"pii_mapping_saturated"}}

程序应依据稳定的 error.code 分支处理，不要匹配提示文案。此错误不附带 Retry-After；即使误收到该响应头，控制台也会忽略。

Retry-After 响应头

Retry-After 是 HTTP 响应头，不是 JSON 错误包体中的字段。例如，Retry-After: 30 表示建议等待 30 秒再重试；它不会自动触发重试，也不保证届时恢复。普通调用方限流仍可返回 HTTP 429 并附带此响应头。

控制台读取响应头后，会转换为本地错误对象的 ApiError.retryAfterSeconds 属性；该属性不属于 API 响应包体。解析器接受整数秒数或 HTTP 日期，忽略无效值或超过 24 小时的等待时间。

排障时记录响应头 X-Request-ID、时间与错误码。X-Request-ID 是客户端关联号，不保证全局唯一；请勿在排障材料中包含密钥或敏感请求正文。

Streaming