エラー
パブリック API は安定した HTTP ステータスコードと、機械可読のエラーエンベロープを使用します。SDK の呼び出し元は、2xx 以外のレスポンスに対して型付きの FabHubApiError を受け取ります。
エラーの形状
{
"error": {
"code": "SCOPE_REQUIRED",
"message": "This credential is missing the items:write scope",
"request_id": "req_8f3a...",
"details": {}
}
}
request_id はほとんどのレスポンスに含まれます。サポートへの問い合わせの際に引用してください。details はバリデーションエラーの際に存在します。message ではなく、安定した error.code で分岐してください。
ステータスコード
| ステータス | 意味 |
|---|---|
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 はレート制限ウィンドウがリセットされた後にのみリトライ可能として扱ってください。書き込みには冪等性キーを使用し、トランスポートの失敗を安全にリトライできるようにしてください。冪等性およびレート制限を参照してください。