--- title: "开放接口错误与限频" description: "处理开放接口的密钥、权限、参数、限频与临时故障,了解重试方式和版本约定。" image: "https://docs.xiu.ai/og.png" --- > XiuAI 文档索引 > 完整文档索引:https://docs.xiu.ai/llms.txt > 阅读前先通过索引确认当前可用页面。 # 开放接口错误与限频 通过 HTTP 状态码判断是否成功。成功响应恒为 `200`;错误响应使用以下格式,部分错误附带可用于处理的字段: ```json { "error": "invalid_request", "field": "startTime" } ``` | HTTP | `error` | 处理方式 | | --- | --- | --- | | `400` | `invalid_request` | 按 `field` 修改参数,不要原样重试 | | `401` | `unauthorized` | 检查密钥是否正确;在[控制台](https://router.xiu.ai/zh/console/open-api)核对是否已吊销或过期,所属账户停用时联系支持 | | `403` | `insufficient_scope` | 在控制台为这把密钥补充接口所需权限,无需更换密钥 | | `404` | `not_found` | 检查基址、版本和请求路径 | | `429` | `rate_limited` | 等待 `retryAfterSeconds` 指定的秒数后重试 | | `500` | `internal` | 设置等待时间和重试上限;持续失败时联系支持 | | `502` | `upstream_unavailable` | 余额或请求记录暂时无法读取,退避后重试 | | 其他 `5xx` | 以响应为准 | 退避并限制重试次数;持续失败时提供请求时间 | `401` 不区分密钥缺失、格式错误、不存在、已吊销、已过期或账户停用。不要依赖响应正文判断具体原因,到控制台查看这把密钥的状态与最近使用时间。 ## 调用频率 每把密钥每分钟最多调用 60 次,按分钟窗口计数。所有接口共享这一额度;在多台机器使用同一把密钥,也共享这一额度。 超限时返回 `429`、`Retry-After` 响应头及 JSON: ```json { "error": "rate_limited", "retryAfterSeconds": 23 } ``` 批量读取时使用 `limit=100`,为同一密钥的其他任务预留调用次数。需要更高频率时联系支持,不要通过签发多把密钥绕过限制。 ## 版本与支持 当前版本为 `/open/v1/*`。同一版本内不会删除或重命名已有字段、改变字段类型或错误码含义;可能增加接口、响应字段或权限。解析 JSON 时忽略未知字段。破坏性变更使用新版本路径,旧版本下线前会另行公告。 签发、调整权限和吊销密钥在[控制台](https://router.xiu.ai/zh/console/open-api)自助完成,见[获取密钥](/open-api/#获取密钥)。提高调用频率或其他问题,可通过[在线客服](https://xiu.ai/zh/)或邮件 [contact@xiu.ai](mailto:contact@xiu.ai) 联系我们。排障时提供请求时间、HTTP 状态码、错误码和密钥末 4 位;涉及某次模型请求时,再附上 `requestId`。不要发送完整密钥。 源文件:https://docs.xiu.ai/open-api/errors/index.mdx