メインコンテンツへスキップ

一般的な API エラー

この記事は、EKB のクラウド プラットフォームを利用するときに発生する可能性のある最も一般的な API エラーを理解するのに役立ちます。さまざまな HTTP ステータス コードと特定のエラー コードの詳細が表示され、これらの問題を効果的に解決するための重要なトラブルシューティング手順が提供されます。エラー応答の形式と API の使用に関連する一般的な落とし穴を理解することで、エラーを処理し、開発エクスペリエンスを向上させるための準備が整います。

エラー応答フォーマット​

すべての API エラーは一貫した形式に従います。

{
  "status_code": 400,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "detail": "Additional error details (optional)"
}

一部のエラーには次のものも含まれる場合があります。

  • error_id: エラーを追跡するための一意の識別子
  • invalid_fields: 検証に失敗したフィールドのリスト (検証エラーの場合)

HTTP ステータス コード​

400 不正なリクエスト​

無効な入力または不正な形式のリクエストによるクライアント側のエラー。

VALIDATION_ERROR

エラー コード: VALIDATION_ERROR ステータス コード: 400

説明: リクエストの検証に失敗しました。リクエスト内の 1 つ以上のフィールドが無効です。

一般的な原因:

  • 必須フィールドが不足しています
    • 無効なフィールド形式 (無効な電子メール、日付形式など)
    • 許容範囲外のフィールド値
    • 無効なデータ型

応答例:

{
  "status_code": 400,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "invalid_fields": ["email", "project_id"]
  }
}

トラブルシューティング:

  1. invalid_fields 配列を確認して、問題のあるフィールドを特定します
  2. API ドキュメントのフィールド要件を確認します。
  3. データ型が予期される形式と一致することを確認します
  4. 必須フィールドがすべて入力されていることを確認します
INVALID_API_KEY

Error Code: PLACEHOLDER_1
Status Code: PLACEHOLDER_2

Description: The provided API key is invalid or malformed.

Troubleshooting:

  1. Verify the API key is correctly copied (no extra spaces)
  2. Check if the API key is active in My Account > API Keys
  3. Ensure you're using the correct API key for your environment
  4. Regenerate the API key if necessary
INVALID_CREDENTIALS

Error Code: PLACEHOLDER_3
Status Code: PLACEHOLDER_4

Description: Authentication credentials are invalid.

Troubleshooting:

  1. Verify email and password are correct
  2. Check if account is locked or disabled
  3. Try resetting your password
  4. Ensure you're using the correct authentication method
INVALID_OR_EXPIRED_JWT_TOKEN

Error Code: PLACEHOLDER_5
Status Code: PLACEHOLDER_6

Description: The JWT token is invalid, expired, or malformed.

Troubleshooting:

  1. Refresh your authentication token
  2. Log out and log back in
  3. Check token expiration time
  4. Verify token is being sent in the correct header format

401 不正​

認証が必要か、認証に失敗しました。

AUTHENTICATION

Error Code: PLACEHOLDER_7
Status Code: PLACEHOLDER_8

Description: Authentication is required to access this resource.

Troubleshooting:

  1. Ensure you're logged in
  2. Check if your session has expired
  3. Verify authentication headers are included in the request
  4. Re-authenticate if necessary
INVALID_BEARER_TOKEN

Error Code: PLACEHOLDER_9
Status Code: PLACEHOLDER_10

Description: The Bearer token provided is invalid.

Troubleshooting:

  1. Verify the token format: PLACEHOLDER_11
  2. Check if the token has expired
  3. Regenerate authentication token
  4. Ensure token is not revoked
EMAIL_IS_NOT_VERIFIED

Error Code: PLACEHOLDER_12
Status Code: PLACEHOLDER_13

Description: Email address has not been verified.

Troubleshooting:

  1. Check your email for verification link
  2. Request a new verification email
  3. Verify email address is correct
  4. Check spam/junk folder

403 禁止​

権限が不十分なため、アクセスが拒否されました。

AUTHORIZATION

Error Code: PLACEHOLDER_14
Status Code: PLACEHOLDER_15

Description: You don't have permission to perform this action.

Troubleshooting:

  1. Verify you have the required role/permissions
  2. Check if you're a member of the project/team
  3. Contact project/team admin to grant access
  4. Ensure you're accessing the correct resource
PERMISSION_DENIED

Error Code: PLACEHOLDER_16
Status Code: PLACEHOLDER_17

Description: Permission denied for the requested operation.

Troubleshooting:

  1. Review your user role and permissions
  2. Check project/team access settings
  3. Verify resource ownership
  4. Contact administrator for access
DOMAIN_NOT_ALLOWED

Error Code: PLACEHOLDER_18
Status Code: PLACEHOLDER_19

Description: Your email domain is not allowed for this operation.

Troubleshooting:

  1. Verify your email domain is whitelisted
  2. Contact administrator to add your domain
  3. Use an allowed email address

404 見つかりません​

要求されたリソースは存在しません。

ENTITY_NOT_FOUND

Error Code: PLACEHOLDER_20
Status Code: PLACEHOLDER_21

Description: The requested resource was not found.

Common Scenarios:

  • Project not found
  • Agent not found
  • Document not found
  • User not found

Troubleshooting:

  1. Verify the resource ID is correct
  2. Check if the resource was deleted
  3. Ensure you have access to the resource
  4. Verify you're using the correct project/workspace
FILE_NOT_FOUND

Error Code: PLACEHOLDER_22
Status Code: PLACEHOLDER_23

Description: The requested file does not exist.

Troubleshooting:

  1. Verify the file ID or path is correct
  2. Check if the file was deleted
  3. Ensure the file is in the expected location
  4. Verify file permissions
FLOW_NOT_FOUND

Error Code: PLACEHOLDER_24
Status Code: PLACEHOLDER_25

Description: The requested workflow/flow was not found.

Troubleshooting:

  1. Verify the flow ID is correct
  2. Check if the flow was deleted
  3. Ensure you have access to the flow
  4. Verify the flow exists in the current project
CONFIG_NOT_FOUND

Error Code: PLACEHOLDER_26
Status Code: PLACEHOLDER_27

Description: Required configuration was not found.

Troubleshooting:

  1. Verify configuration exists
  2. Check configuration setup in settings
  3. Ensure required services are configured
  4. Review configuration documentation

500 内部サーバーエラー​

調査が必要なサーバー側のエラー。

ENGINE_OPERATION_FAILURE

Error Code: PLACEHOLDER_28
Status Code: PLACEHOLDER_29

Description: An internal engine operation failed.

Troubleshooting:

  1. Retry the request after a few moments
  2. Check system status at PLACEHOLDER_30
  3. If persistent, contact support with error details
  4. Provide error ID if available
EXTERNAL_SERVICE

Error Code: PLACEHOLDER_31
Status Code: PLACEHOLDER_32

Description: An external service required for this operation failed.

Common Scenarios:

  • LLM provider API failure
  • Third-party integration failure (Google Drive, Slack, etc.)
  • External API timeout

Troubleshooting:

  1. Check external service status
  2. Verify API keys/credentials for external services
  3. Retry the request
  4. Check integration configuration
  5. Contact support if issue persists
INFRASTRUCTURE

Error Code: PLACEHOLDER_33
Status Code: PLACEHOLDER_34

Description: Infrastructure error (database, storage, etc.).

Troubleshooting:

  1. Retry the request
  2. Check system status
  3. If persistent, contact support
  4. Provide error details and timestamp
OPEN_AI_FAILED

Error Code: PLACEHOLDER_35
Status Code: PLACEHOLDER_36

Description: OpenAI API call failed.

Troubleshooting:

  1. Check OpenAI service status
  2. Verify API key is valid and has credits
  3. Check rate limits
  4. Retry with exponential backoff
  5. Verify model availability

503 サービスは利用できません​

サービスが一時的に利用できなくなりました。

EXECUTION_TIMEOUT

Error Code: PLACEHOLDER_37
Status Code: PLACEHOLDER_38

Description: Operation timed out.

Troubleshooting:

  1. Retry the request
  2. Simplify the operation if possible
  3. Check if system is under heavy load
  4. Break down large operations into smaller ones
  5. Contact support if timeout persists

ビジネス ロジック エラー​

QUOTA_EXCEEDED

Error Code: PLACEHOLDER_39
Status Code: PLACEHOLDER_40 or PLACEHOLDER_41

Description: You have exceeded your quota limit.

Troubleshooting:

  1. Check your current usage in My Account > Dashboard
  2. Review subscription limits
  3. Upgrade your plan if needed
  4. Wait for quota reset period
  5. Contact sales for quota increase
FEATURE_DISABLED

Error Code: PLACEHOLDER_42
Status Code: PLACEHOLDER_43

Description: This feature is disabled for your account.

Troubleshooting:

  1. Check your subscription plan
  2. Verify feature availability
  3. Upgrade plan if feature requires higher tier
  4. Contact support for feature access
FLOW_IN_USE

Error Code: PLACEHOLDER_44
Status Code: PLACEHOLDER_45

Description: The workflow is currently in use and cannot be modified.

Troubleshooting:

  1. Wait for active executions to complete
  2. Cancel active workflow runs
  3. Check workflow execution status
  4. Retry after executions complete
EXISTING_USER

Error Code: PLACEHOLDER_46
Status Code: PLACEHOLDER_47

Description: User with this email already exists.

Troubleshooting:

  1. Try logging in instead of signing up
  2. Use password reset if you forgot credentials
  3. Use a different email address
  4. Contact support if account recovery is needed

統合固有のエラー​

INVALID_APP_CONNECTION

Error Code: PLACEHOLDER_48
Status Code: PLACEHOLDER_49

Description: Invalid or expired app connection (OAuth integration).

Troubleshooting:

  1. Re-authenticate the integration
  2. Check OAuth token expiration
  3. Verify integration credentials
  4. Reconnect the integration in settings
INVALID_SAML_RESPONSE

Error Code: PLACEHOLDER_50
Status Code: PLACEHOLDER_51

Description: Invalid SAML response from SSO provider.

Troubleshooting:

  1. Verify SSO configuration
  2. Check SAML metadata URL
  3. Ensure SSO provider is accessible
  4. Contact support for SSO configuration review
RATE_LIMITED

Error Code: PLACEHOLDER_52 or PLACEHOLDER_53
Status Code: PLACEHOLDER_54

Description: API rate limit exceeded.

Troubleshooting:

  1. Wait for rate limit window to reset
  2. Implement exponential backoff
  3. Reduce request frequency
  4. Check rate limit headers in response
  5. Upgrade plan for higher rate limits

助けを求める​

ここに記載されていないエラーが発生した場合、またはサポートが必要な場合は、次の手順を実行してください。

  1. エラーの詳細を確認: エラー コード、メッセージ、および error_id をメモします。
  2. システム ステータスを確認: 既知の問題については、status.getodin.ai にアクセスしてください。
  3. ドキュメントの確認: 関連する API ドキュメントを確認します。
  4. サポートに連絡: Support に次の内容を電子メールで送信します。
    • エラーコードとメッセージ
    • エラー ID (利用可能な場合)
    • 再現手順
    • リクエスト/レスポンスの詳細 (サニタイズ済み)
    • エラーのタイムスタンプ