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が見つかりませんでした。" |
レコード/todoが存在しないか、ユーザーにアクセス権がありません |
TODO_LIST_NOT_FOUND |
"Todoリストが見つかりませんでした。" |
リストが存在しないか、ユーザーにアクセス権がありません |
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です。" |
リクエスト内の1つ以上の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 |
"Todoが多すぎます。" |
レコード制限を超えました |
TOO_MANY_OPTIONS |
"オプションが多すぎます。" |
選択フィールドオプションの制限を超えました |
MAX_FILE_SIZE |
"最大ファイルサイズは4.8GBです" |
ファイルアップロードサイズ制限を超えました |
リソースの競合
| エラーコード |
メッセージ |
説明 |
TAG_ALREADY_EXISTS |
"タグはすでに存在します。" |
同じ名前のタグがプロジェクトに存在します |
COMPANY_SLUG_ALREADY_EXISTS |
"会社はすでに存在します。" |
会社のスラッグ/URLは使用されています |
USER_ALREADY_EXISTS |
"ユーザーはすでに存在します。" |
ユーザーのメールはすでに登録されています |
ALREADY_INVITED |
"ユーザーはすでに招待されています。" |
ユーザーはすでに保留中の招待があります |
USER_ALREADY_IN_PROJECT |
"ユーザーはすでにこのプロジェクトにいます。" |
ユーザーはすでにプロジェクトにアクセス権があります |
FILE_TYPE_NOT_ALLOWED |
"許可されていないファイルタイプ。" |
アップロードされたファイルタイプが制限されています |
権限とアクセスエラー
| エラーコード |
メッセージ |
説明 |
UNABLE_TO_DELETE_ONLY_ADMIN |
"会社の唯一の管理者を削除できません。" |
最後の管理者を削除できません |
UNABLE_TO_UPDATE_OWNER |
"OWNERを更新できません。" |
オーナーの権限を変更できません |
TODO_LIST_IS_HIDDEN |
"Todoリストは非表示です。" |
ユーザーの役割からリストが非表示になっています |
COMPANY_NOT_ACTIVE |
"会社はアクティブではありません。" |
会社のサブスクリプションが非アクティブです |
PROJECT_NOT_ACTIVE |
"プロジェクトはアクティブではありません。" |
プロジェクトはアーカイブされているか非アクティブです |
データ整合性エラー
| エラーコード |
メッセージ |
説明 |
UNABLE_TO_DELETE_LIST_WITH_TODOS |
"Todoがあるリストを削除できません。" |
リストは削除するために空でなければなりません |
UNABLE_TO_DELTE_FILE |
"ファイルを削除できません。" |
ファイルの削除に失敗しました（コードのタイプミス） |
UNABLE_TO_MOVE_TODO |
"Todoを移動できません。" |
リスト間でレコードを移動できません |
DEPENDENCY_HAS_DEPENDENCY |
"依存関係が依存関係を持っています" |
循環依存関係が検出されました |
TODO_DEPENDS_ON_ITSELF |
"Todoは自分自身に依存しています" |
自己参照依存関係 |
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 |
"税IDを保存できません" |
税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 - 機能にはサブスクリプションが必要です
関連文書