API 网关
错误码
/v1/* 网关的错误形状与常见错误。
错误形状
/v1/* 网关保持上游兼容的裸响应，错误统一为：
{
"error": {
"type": "invalid_request_error",
"code": "model_not_found",
"message": "The model 'foo' does not exist or is not available."
}
}type 与 OpenAI / Anthropic 的错误分类对齐：invalid_request_error、authentication_error、permission_error、not_found_error、rate_limit_error、api_error 等。
网关错误不会包成管理接口的 { code, message, data } 包装；那是 /api/* 的约定。判断响应是否成功以 HTTP 状态码为准。
常见错误
| HTTP | 场景 | 处理 |
|---|---|---|
| 401 | 密钥缺失、格式错误或已吊销 | 检查 Authorization / x-api-key，必要时换新密钥 |
| 403 | 密钥无权访问该模型 / 空间 | 换有权限的密钥或联系空间管理员 |
| 404 | 模型不存在或路径写错 | 对照模型目录与端点文档 |
| 429 | 触发限流或余额不足 | 降低频率；余额不足先充值 |
| 5xx | 上游故障或网关异常 | 稍后重试；持续失败联系运营方 |
重试建议
- 对 429 / 5xx 使用指数退避重试，对 4xx（除 429）不重试。
- 流式请求建议在断连后从新请求恢复，而不是续读旧流。