Unif API Docs错误
UnifAPI 返回给智能体和 HTTP 客户端的每一种错误，它们的含义，以及如何恢复。
无论调用的是哪个公开数据操作，错误总是以相同的信封返回：
{
"error": {
"type": "rate_limited",
"message": "Workspace rate limit exceeded.",
"request_id": "unif_5471f8cfa3814204a280b73df8c93167"
}
}error.type来自一个 封闭词汇表（见下表）——稳定、机器可读，可安全地供智能体和客户端用于分支判断。error.message面向人类阅读，可能在未通知的情况下变更。error.request_id是 UnifAPI 追踪 id。请在支持请求中附上它。error.issues仅当type = validation_error时出现——它是原始的 Zod issue 列表。
HTTP 状态码与 type 相对应——客户端可以选择它们偏好的任一信号。
参考
| 状态码 | type | 何时发生 | 恢复方式 |
|---|---|---|---|
| 400 | validation_error | 请求未通过网关侧校验（查询有误、缺少 body 字段）。 | 检查 error.issues。修正请求。 |
| 400 | invalid_id | 提供的 id 语法上有效，但未被公开来源接受。 | 使用真实的 id。 |
| 401 | unauthorized | OAuth 或 API key 凭据缺失、格式错误、被吊销或被禁用。 | 重新认证或轮换 key。 |
| 404 | not_found | 资源（视频、用户、房间……）不存在、已删除或为私有。 | 确认 id；某些资源是私有的，按设计返回 404。 |
| 429 | rate_limited | 工作区或来源速率限制已超出。 | 遵守 Retry-After。参见 速率限制。 |
| 500 | internal_error | UnifAPI 自身失败（未捕获的异常）。 | 可以安全重试。如果持续出现，请上报 request_id。 |
| 500 | response_shape_error | 来源数据不再与已发布的数据结构匹配。 | 上报 request_id——漂移是一个 bug。 |
| 502 | upstream_error | 公开数据来源返回了 UnifAPI 无法恢复的错误。 | 检查 error.message。 |
| 503 | upstream_unavailable | 公开数据来源超时或无法访问。 | 使用指数退避重试。 |
上表是当前错误词汇表的公开契约。
校验错误剖析
对于 validation_error，issues 数组携带原始的 Zod issue 列表，以便智能体或调用方能将错误映射回字段：
{
"error": {
"type": "validation_error",
"message": "Request validation failed.",
"issues": [
{
"code": "too_big",
"maximum": 50,
"type": "number",
"inclusive": true,
"path": ["limit"],
"message": "Number must be less than or equal to 50"
}
]
}
}务必记录 request_id
每个错误响应在 UnifAPI 能够附上时都会携带 request_id。请记录它并在支持请求中附上；它是调试失败的 Skill 运行或 HTTP 调用的最快方式。