一言（简版）API故障定位指南：基于真实错误的排查与修复
适用场景
一言（简版）API 返回随机的中文句子，适合在站点页脚、小程序欢迎语、控制台启动提示或任何需要“一句话点缀”的场景中嵌入。本指南面向已经或准备使用该接口的开发者，重点解决接入过程中最容易遇到的故障，而非介绍功能本身。
接口能力边界
- 请求方法：GET
- 地址：
https://v1.apizero.cn/api/yiyan - QPS（每秒请求配额）：20 次/秒
- 返回格式：默认为 JSON，也可通过
format=text获取纯文本 - 数据池：约 370 条（以响应中的
total_pool为准，会动态更新）
调用方需要清楚：这是一个轻量、无状态的接口，不保证每次返回不同句子；如果连续请求频率超过 20 QPS，会被限流（HTTP 429）。另外，接口不支持自定义池子或分类过滤。
鉴权与参数
鉴权方式
需要在 HTTP 请求头中携带X-API-Key，值为你的密钥。密钥获取方式以平台文档为准。
Query 参数
| 参数名 | 必填 | 类型 | 默认值 | 可选值 | 说明 |
|---|---|---|---|---|---|
| format | 否 | string | json | json / text | 指定返回格式。text时直接返回纯文本字符串，没有外层 JSON。 |
curl 示例（可复制）
以下命令演示携带 API Key 获取 JSON 格式的一言：
curl -sS \ -X GET \ -H "X-API-Key: YOUR_API_KEY_HERE" \ "https://v1.apizero.cn/api/yiyan?format=json"如果希望纯文本，改为：
curl -sS \ -X GET \ -H "X-API-Key: YOUR_API_KEY_HERE" \ "https://v1.apizero.cn/api/yiyan?format=text"注意：请将
YOUR_API_KEY_HERE替换为真实的 API Key。不要在公开仓库中硬编码密钥。
返回值解读
JSON 格式 (format=json)
成功响应示例：
{ "code": 0, "data": { "content": "落霞与孤鹜齐飞，秋水共长天一色。", "length": 16, "total_pool": 370 }, "msg": "成功" }字段说明：
code：业务状态码，0 表示成功。非 0 表示异常（详见错误列表）。data.content：随机句子字符串。data.length：句子字符数（汉字计数）。data.total_pool：当前数据池总句子数，可用于监控池更新。msg：状态描述。
纯文本格式 (format=text)
直接返回句子文本，例如：
落霞与孤鹜齐飞，秋水共长天一色。无额外包裹，无换行符（除末尾）。注意此时 HTTP 状态码仍遵循 HTTP 规范，但业务错误会导致返回非 200 状态码。
常见错误与排查
下面是调用中最容易遇到的几类错误，按照 HTTP 状态码分类。
1. 400 Bad Request —— 参数错误
现象：
HTTP/1.1 400 Bad Request {"code":1,"msg":"参数错误"}可能原因：
- 传入了不支持的
format值（如format=xml）。 - 请求行格式异常（如 URL 编码问题）。
诊断：
- 确认只使用
json或text。 - 检查 URL 是否包含多余空格或无效字符。
修复：
# 正确示例 curl -sS -H "X-API-Key: xxx" "https://v1.apizero.cn/api/yiyan?format=json"2. 403 Forbidden —— 鉴权失败
现象：
HTTP/1.1 403 Forbidden {"code":-1,"msg":"鉴权失败"}原因：
- 未携带
X-API-Key头。 - API Key 错误、过期或被吊销。
- IP 白名单限制（如果平台启用）。
诊断：
- 检查请求头中是否包含
X-API-Key。使用-v查看详细：curl -v -sS -H "X-API-Key: xxx" "https://v1.apizero.cn/api/yiyan" - 验证 API Key 字符串是否完整复制（注意前后空格）。
修复：
- 重新生成密钥并正确配置在环境变量中。
- 如果使用了代理，确认代理未篡改请求头。
3. 429 Too Many Requests —— 限流
现象：
HTTP/1.1 429 Too Many Requests {"code":-3,"msg":"请求过于频繁，请稍后再试"}原因：
- 短时间内请求超过 20 次/秒。
- 并发请求数超过接口允许（总 QPS 20）。
诊断：
- 在短时间内手动连续执行 curl 测试，观察返回。
- 检查代码中是否未加节流（如 for 循环中无 sleep）。
修复：
- 在应用层加入限速：每 50ms 最多发一次请求，或使用令牌桶。
- 对于批量获取场景（如启动时预取多条），改用一次请求后本地缓存池拉取多条数据？但接口一次只返回一句，暂无批量接口。合理做法是降低请求频率，或每次间隔 ≥100ms。
- 使用
Retry-After响应头（如果返回）的数值来等待。
4. 500 Internal Server Error —— 服务端异常
现象：
HTTP/1.1 500 Internal Server Error {"code":-2,"msg":"服务器内部错误"}原因：多数时候是服务端临时问题（如数据库连接波动、池未加载）。
诊断：
- 等待几秒后重试，看是否恢复。
- 检查网络链路：DNS 解析、中间代理。
- 确认使用的是正确的域名
v1.apizero.cn，非apizero.cn二次跳转。
修复：
- 加入指数退避重试：
第一次等待1秒，第二次2秒，第三次4秒……最长等待30秒。 - 如果持续 500，联系 API 提供方。
5. timeout / 连接拒绝 —— 网络问题
现象：
curl: (28) Connection timed out after XXXX milliseconds curl: (7) Failed to connect to v1.apizero.cn port 443: Connection refused原因：
- 本地网络不通（公司内网防火墙、代理拦截）。
- DNS 解析失败。
- 接口服务宕机（概率低）。
诊断：
- 使用
ping v1.apizero.cn检查网络可达性。 - 使用
curl -v --connect-timeout 10 https://v1.apizero.cn/api/yiyan观察连接阶段。 - 检查是否被本地 HTTPS 证书拦截（加
-k仅用于测试，生产环境不应忽略证书）。
修复：
- 调整防火墙规则，放行
443端口。 - 配置正确代理（
--proxy参数）。 - 如果使用 HTTP 而非 HTTPS，请求应使用 HTTPS（接口强制 TLS）。
工程化注意事项
密钥管理：不要将密钥硬编码在代码中。建议通过环境变量
APIZERO_API_KEY注入，生产环境使用密钥管理服务。日志记录：在每次 API 调用前后打印请求标识、耗时和响应状态码，方便事后排查。
重试策略：对于 429 和 5xx 错误，实现有限次数的重试（如 3 次），间隔递增。对 4xx（除 429）不要重试，因为修改请求才是根本。
错误分类：在代码中区分“可重试”和“不可重试”错误。例如：
- 可重试：429、500、网络超时。
- 不可重试：400、403（需人工干预）。
响应解析容错：即使
format=json，也要处理偶发的非 JSON 响应（如网关返回 HTML）。使用 try-catch 包裹 JSON 解析。资源释放：HTTP 客户端需正确关闭连接、设置超时。避免连接泄漏导致程序挂起。
参考文档
- 一言（简版）API 文档：https://apizero.cn/aidocs/yiyan
- 原始文档（需准备查看）：https://apizero.cn/aidocs/yiyan/raw.md