错误
公共 API 使用稳定的 HTTP 状态码和机器可读的错误信封。对于任何非 2xx 响应，SDK 调用方都会收到一个类型化的 FabHubApiError。
错误结构
{
"error": {
"code": "SCOPE_REQUIRED",
"message": "This credential is missing the items:write scope",
"request_id": "req_8f3a...",
"details": {}
}
}
大多数响应都包含 request_id - 在支持请求中请引用它。details 在验证错误时出现。请基于稳定的 error.code 进行分支判断，而非 message。
状态码
| 状态 | 含义 |
|---|---|
400 | 无效请求或验证错误 |
401 | 凭据缺失、无效、过期或已吊销 |
403 | 缺少作用域、套餐限制或 IP 允许列表拒绝 |
404 | 资源未找到 |
409 | 幂等冲突（密钥被复用但负载不同） |
429 | 超出速率限制 |
500 | 服务器错误 |
错误代码
BAD_REQUEST、UNAUTHORIZED、FORBIDDEN、NOT_FOUND、CONFLICT、RATE_LIMITED、INTERNAL_ERRORSCOPE_REQUIRED- 凭据缺少所需的作用域PLAN_REQUIRED- 租户的套餐不包含此能力OBJECT_ACCESS_DENIED- 被引用的对象在租户范围之外TENANT_DISABLED、ENDPOINT_DISABLED- 紧急停用开关MCP_CONFIRMATION_REQUIRED- 写/破坏性 MCP 工具需要显式确认
示例
{ "error": { "code": "NOT_FOUND", "message": "Item not found", "request_id": "req_1a..." } }
{ "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded; retry after the window resets", "request_id": "req_2b..." } }
客户端指南
请将 401 和 403 视为配置或权限问题，而非可重试的失败。仅在速率限制窗口重置后才将 429 视为可重试。在写操作上使用幂等密钥，以便安全地重试传输失败。参见幂等性和速率限制。