エラーとレート制限

エラーの形式

すべてのAPIエラーは、次の構造のJSONを返します。

{
  "error": "Short error description",
  "detail": "Extended description (optional)"
}

一部のエンドポイントでは、Django REST Frameworkのデフォルトとして、次の形式で返される場合もあります。

{
  "detail": "Error message"
}

HTTPステータスコード

ステータス	意味	発生条件
200	成功	リクエストが成功した場合
400	不正なリクエスト	パラメータが不足しているか、無効な場合
401	認証エラー	認証トークンがないか、有効期限が切れているか、無効な場合
403	アクセス禁止	トークンに必要なスコープまたはワークスペースへのアクセス権がない場合
404	見つかりません	リソースが存在しないか、ワークスペースに同期済みデータがない場合
405	許可されていないメソッド	エンドポイントに対して誤ったHTTPメソッドを使用した場合
422	処理できないエンティティ	リクエスト本文の検証に失敗した場合
429	リクエスト過多	レート制限を超えた場合
500	内部サーバーエラー	予期しないサーバーエラーが発生した場合
503	サービス利用不可	Elasticsearchまたはその他の依存サービスが停止している場合

レート制限

V1 API（サービストークン）

区分	上限	適用単位
バースト	10秒あたり20リクエスト	トークンごと
時間枠	15分あたり600リクエスト	トークンごと

ユーザーAPI（JWT）

区分	上限	適用単位
認証済み	毎分100リクエスト	ユーザーごと
匿名	毎分20リクエスト	IPごと

レート制限ヘッダー

レート制限によってリクエストが制限されると、レスポンスには次の情報が含まれます。

HTTP/1.1 429 Too Many Requests
Retry-After: 30

レート制限への対処： Retry-Afterで指定された時間（秒）が経過してから再試行してください。429レスポンスが繰り返し返される場合は、指数バックオフを実装してください。

よくあるエラーの発生例

認証エラー

// Missing Authorization header
{"detail": "Authentication credentials were not provided."}

// Invalid or expired JWT
{"detail": "Given token not valid for any token type", "code": "token_not_valid"}

// Invalid service token
{"error": "Invalid or revoked service token."}

// Expired service token
{"error": "Token has expired."}

権限エラー

// Token missing required scope
{"error": "Token does not have the required scope: graph:search"}

// Workspace not in token's allowed list
{"error": "Workspace not allowed for this token."}

検証エラー

// Missing required parameter
{"error": "workspace_id is required."}

// Invalid UUID format
{"error": "Invalid node_id format."}

// Query too long (V1 API)
{"error": "Query too long (max 256 characters)."}

// Disallowed characters in query
{"error": "Query contains disallowed characters."}

リソースエラー

// Workspace not synced
{"error": "No synced data found for this workspace."}

// Node not found
{"error": "Node not found."}

// Elasticsearch unavailable
{"error": "Search service unavailable."}