Blue GraphQL API 中所有錯誤代碼的綜合參考，按類別組織
錯誤回應格式
Blue 的 GraphQL API 根據 GraphQL 規範以標準化格式返回錯誤。當發生錯誤時，回應會包含一個 errors 陣列，詳細說明發生了什麼問題。
示例錯誤回應
{
"errors": [
{
"message": "Todo was not found.",
"extensions": {
"code": "TODO_NOT_FOUND"
}
}
]
}
錯誤結構
每個錯誤對象包含：
- message: 錯誤的可讀描述
- extensions.code: 用於程式化處理的機器可讀錯誤代碼
生產環境錯誤安全
Blue 實施了一個錯誤暴露的安全系統：
- 安全錯誤: 將實際錯誤代碼和消息顯示給客戶端
- 非安全錯誤: 返回通用的
INTERNAL_SERVER_ERROR 以隱藏敏感細節
- 資源未找到: 所有
*_NOT_FOUND 錯誤被視為安全並始終暴露
錯誤類別
Blue 定義了 108 個自定義錯誤代碼，按以下類別組織：
認證與授權錯誤
| 錯誤代碼 |
消息 |
描述 |
UNAUTHENTICATED |
"需要認證。" |
請求需要認證但未提供 |
FORBIDDEN |
"您未獲授權。" |
已認證但缺少所需權限 |
資源未找到錯誤（共 52 個）
核心資源
| 錯誤代碼 |
消息 |
描述 |
TODO_NOT_FOUND |
"待辦事項未找到。" |
記錄/待辦事項不存在或用戶缺乏訪問權限 |
TODO_LIST_NOT_FOUND |
"待辦列表未找到。" |
列表不存在或用戶缺乏訪問權限 |
PROJECT_NOT_FOUND |
"項目未找到。" |
項目不存在或用戶缺乏訪問權限 |
COMPANY_NOT_FOUND |
"公司未找到。" |
公司不存在或用戶缺乏訪問權限 |
USER_NOT_FOUND |
"用戶未找到。" |
用戶在系統中不存在 |
自定義字段與表單
| 錯誤代碼 |
消息 |
描述 |
CUSTOM_FIELD_NOT_FOUND |
"自定義字段未找到。" |
自定義字段不存在 |
CUSTOM_FIELD_OPTION_NOT_FOUND |
"自定義字段選項未找到。" |
選擇字段選項不存在 |
FORM_NOT_FOUND |
"表單未找到。" |
表單模板不存在 |
FORM_FIELD_NOT_FOUND |
"表單字段未找到。" |
表單字段不存在 |
項目組件
| 錯誤代碼 |
消息 |
描述 |
TAG_NOT_FOUND |
"標籤未找到。" |
標籤在項目中不存在 |
AUTOMATION_NOT_FOUND |
"自動化未找到。" |
自動化規則不存在 |
CHART_NOT_FOUND |
"圖表未找到。" |
儀表板圖表不存在 |
WEBHOOK_NOT_FOUND |
"Webhook 未找到。" |
Webhook 配置不存在 |
TEMPLATE_NOT_FOUND |
"模板未找到。" |
項目模板不存在 |
評論與活動
| 錯誤代碼 |
消息 |
描述 |
COMMENT_NOT_FOUND |
"評論未找到。" |
評論不存在 |
ACTIVITY_NOT_FOUND |
"活動未找到。" |
活動日誌條目不存在 |
REACTION_NOT_FOUND |
"反應未找到。" |
評論反應不存在 |
其他資源
| 錯誤代碼 |
消息 |
描述 |
FILE_NOT_FOUND |
"文件未找到。" |
文件附件不存在 |
SUBSCRIPTION_NOT_FOUND |
"訂閱未找到。" |
計費訂閱不存在 |
INVOICE_NOT_FOUND |
"發票未找到。" |
發票記錄不存在 |
CHECKLIST_NOT_FOUND |
"檢查清單未找到。" |
檢查清單不存在 |
CHECKLIST_ITEM_NOT_FOUND |
"檢查清單項目未找到。" |
檢查清單項目不存在 |
PROJECT_ROLE_NOT_FOUND |
"項目角色未找到。" |
自定義項目角色不存在 |
PROJECT_ACCESS_NOT_FOUND |
"項目訪問未找到。" |
用戶項目訪問不存在 |
NOTIFICATION_NOT_FOUND |
"通知未找到。" |
通知不存在 |
DASHBOARD_NOT_FOUND |
"儀表板未找到。" |
儀表板不存在 |
KEY_NOT_FOUND |
"密鑰未找到。" |
設定密鑰不存在 |
驗證錯誤
| 錯誤代碼 |
消息 |
描述 |
BAD_USER_INPUT |
"無效的輸入。" |
通用輸入驗證失敗 |
VALIDATION_ERROR |
"無效的參數" |
請求參數驗證失敗 |
BAD_EMAIL |
"您需要輸入有效的電子郵件。" |
無效的電子郵件格式 |
INVALID_IDS |
"無效的 ID。" |
請求中的一個或多個 ID 無效 |
PHONE_INVALID |
"電話無效。" |
無效的電話號碼格式 |
URL_INVALID |
"URL 無效。" |
無效的 URL 格式 |
INVALID_RECURRING_DUE_DATE |
"無效的重複任務截止日期" |
重複任務日期驗證失敗 |
INVALID_COLOR |
"無效的顏色" |
顏色值不符合預期格式 |
商業邏輯錯誤
限制與配額
| 錯誤代碼 |
消息 |
描述 |
COMPANY_LIMIT |
"您已達到帳戶的公司限制。" |
最大公司數量已達到 |
PROJECT_LIMIT |
"您已達到公司項目的限制。" |
最大項目數量已達到 |
USER_LIMIT |
"您已達到公司用戶的限制。" |
最大用戶數量已達到 |
PROJECT_TEMPLATE_LIMIT |
"您已達到公司模板的限制。" |
最大模板數量已達到 |
CUSTOM_FIELD_LIMIT |
"自定義字段限制已達到。" |
最大自定義字段數量已達到 |
TODO_LIST_LIMIT |
"您已達到項目的列表限制。" |
每個項目的最大列表數量 |
TOO_MANY_TODOS |
"待辦事項過多。" |
記錄數量限制已超過 |
TOO_MANY_OPTIONS |
"選項過多。" |
選擇字段選項數量限制已超過 |
MAX_FILE_SIZE |
"最大文件大小為 4.8GB" |
文件上傳大小限制已超過 |
資源衝突
| 錯誤代碼 |
消息 |
描述 |
TAG_ALREADY_EXISTS |
"標籤已存在。" |
項目中存在同名標籤 |
COMPANY_SLUG_ALREADY_EXISTS |
"公司已存在。" |
公司 slug/URL 已被佔用 |
USER_ALREADY_EXISTS |
"用戶已存在。" |
用戶電子郵件已註冊 |
ALREADY_INVITED |
"用戶已被邀請。" |
用戶已經有待處理的邀請 |
USER_ALREADY_IN_PROJECT |
"用戶已在此項目中。" |
用戶已經有項目訪問權限 |
FILE_TYPE_NOT_ALLOWED |
"不允許的文件類型。" |
上傳的文件類型受到限制 |
權限與訪問錯誤
| 錯誤代碼 |
消息 |
描述 |
UNABLE_TO_DELETE_ONLY_ADMIN |
"無法刪除公司中的唯一管理員。" |
無法移除最後一位管理員 |
UNABLE_TO_UPDATE_OWNER |
"無法更新擁有者。" |
無法修改擁有者權限 |
TODO_LIST_IS_HIDDEN |
"待辦列表被隱藏。" |
列表對用戶的角色隱藏 |
COMPANY_NOT_ACTIVE |
"公司未激活。" |
公司訂閱未激活 |
PROJECT_NOT_ACTIVE |
"項目未激活。" |
項目已存檔/未激活 |
數據完整性錯誤
| 錯誤代碼 |
消息 |
描述 |
UNABLE_TO_DELETE_LIST_WITH_TODOS |
"無法刪除有待辦事項的列表。" |
列表必須為空才能刪除 |
UNABLE_TO_DELTE_FILE |
"無法刪除文件。" |
文件刪除失敗（代碼中有錯字） |
UNABLE_TO_MOVE_TODO |
"無法移動待辦事項。" |
無法在列表之間移動記錄 |
DEPENDENCY_HAS_DEPENDENCY |
"依賴項有依賴項" |
檢測到循環依賴 |
TODO_DEPENDS_ON_ITSELF |
"待辦事項依賴於自身" |
自我參考依賴 |
Stripe/支付錯誤
| 錯誤代碼 |
消息 |
描述 |
STRIPE_CREATING_CUSTOMER |
"在 Stripe 中創建客戶時出錯。" |
Stripe 客戶創建失敗 |
STRIPE_ALREADY_SUBSCRIBED |
"已經訂閱。" |
存在有效訂閱 |
STRIPE_MISSING_PAYMENT_METHOD |
"缺少支付方式。" |
沒有支付方式 |
STRIPE_CREATING_SUBSCRIPTION |
"在 Stripe 中創建訂閱時出錯。" |
訂閱創建失敗 |
STRIPE_UPDATING_SUBSCRIPTION |
"在 Stripe 中更新訂閱時出錯。" |
訂閱更新失敗 |
STRIPE_CHECKOUT_SESSION |
"在 Stripe 中創建結帳會話時出錯。" |
結帳會話創建失敗 |
STRIPE_CUSTOMER_PORTAL |
"在 Stripe 中創建客戶門戶時出錯。" |
門戶會話創建失敗 |
STRIPE_TAX_ID |
"無法保存稅號" |
稅號驗證/保存失敗 |
PAYMENT_REQUIRED |
"需要支付。" |
功能需要有效訂閱 |
NO_PAYMENT_REQUIRED |
"不需要支付。" |
操作不需要支付 |
認證與會話錯誤
| 錯誤代碼 |
消息 |
描述 |
INVALID_CREDENTIALS |
"無效的憑證。" |
用戶名/密碼不正確 |
EXPIRED_RESET_TOKEN |
"重置令牌已過期。" |
密碼重置令牌已過期 |
OAUTH_FAILED |
"OAuth 流程失敗。" |
OAuth 認證失敗 |
SAML_NOT_ENABLED |
"SSO (SAML) 未啟用。" |
SAML SSO 未配置 |
SSO_AUTO_PROVISION_DISABLED |
"自動配置已禁用。" |
無法自動創建 SSO 用戶 |
速率限制
速率限制由 graphql-rate-limit 套件處理，具有不同的配置：
| 限制類型 |
窗口 |
最大請求 |
應用於 |
| Standard |
60s |
500 |
Most queries/mutations |
| Sensitive |
300s |
10 |
Password reset, auth operations |
| Expensive |
60s |
20 |
Complex queries, bulk operations |
| Search |
60s |
60 |
Search operations |
| File Upload |
60s |
100 |
File upload operations |
當達到速率限制時，您將收到一個標準的 GraphQL 錯誤，消息指示超過了限制。
系統與內部錯誤
| 錯誤代碼 |
消息 |
描述 |
INTERNAL_SERVER_ERROR |
"內部伺服器錯誤。" |
生產環境中非安全錯誤的通用錯誤 |
UNKNOWN_ERROR |
"未知錯誤。" |
發生了意外錯誤 |
RESOLVER_NOT_FOUND |
"解析器未找到" |
缺少 GraphQL 解析器 |
FIELD_NOT_IN_SCHEMA |
"字段不在架構中" |
請求的字段不存在 |
錯誤處理最佳實踐
客戶端處理
try {
const result = await client.mutate({
mutation: CREATE_TODO,
variables: { input }
});
} catch (error) {
if (error.graphQLErrors?.length > 0) {
const errorCode = error.graphQLErrors[0].extensions?.code;
switch (errorCode) {
case 'UNAUTHENTICATED':
// Redirect to login
break;
case 'TODO_NOT_FOUND':
// Show "Record not found" message
break;
case 'VALIDATION_ERROR':
// Display validation errors
break;
default:
// Show generic error message
}
}
}
常見錯誤場景
- 需要認證:
UNAUTHENTICATED - 用戶需要登錄
- 權限被拒絕:
FORBIDDEN - 用戶缺少所需角色/權限
- 資源未找到:
*_NOT_FOUND - 資源不存在或用戶無法訪問
- 驗證失敗:
VALIDATION_ERROR, BAD_USER_INPUT - 檢查輸入參數
- 速率限制: 檢查速率限制標頭並實施退避
- 需要支付:
PAYMENT_REQUIRED - 功能需要訂閱
相關文檔
- 認證 - 如何對 API 請求進行認證
- 發送請求 - 請求格式和標頭
- 速率限制 - 詳細的速率限制信息