錯誤與速率限制 - API 文件

錯誤格式

所有 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."}