Minds Team

エラーと制限

APIエラー、ステータスコード、プランベースのリソース制限を理解する。

APIエラー、レート制限、プラン制限を理解する。

エラー応答フォーマット

すべてのエラーは一貫したフォーマットに従います：

{
  "statusCode": 400,
  "statusMessage": "Name is required",
  "message": "Name is required",
  "url": "/api/v1/minds",
  "error": true
}
フィールド説明
statusCodeHTTPステータスコード
statusMessage人間が読み取れるエラー説明（ハンドラーによってエラーごとに設定されます - 検証エラーの場合、これは特定の問題です。例："Mind not found"または"Invalid Mind ID format"）
messagev1エラーのためのstatusMessageと同じ内容。デバッグビルドの5xx応答におけるスタック/追加コンテキスト用に予約されています。
urlリクエストパス（Nuxt H3によって追加されます）
errorエラー応答のためのtrue（Nuxt H3によって追加されます）

プログラムによる処理には常にstatusCodeを頼りにし、人間が読み取れる理由にはstatusMessage（またはmessage）を使用してください。urlおよびerrorフィールドは、基盤となるフレームワークからの便利なメタデータです。

HTTPステータスコード

2xx 成功

コードステータス説明
200OKリクエスト成功
201作成済みリソースが正常に作成されました（例：POST /minds、POST /minds/{id}/knowledge）
202受理済み非同期処理のためにリクエストが受理されました（例：POST /minds/{id}/knowledgeとkeywords）
204コンテンツなしリクエスト成功、応答ボディなし（例：DELETE /minds/{id}/knowledge/{itemId}）

4xx クライアントエラー

コードステータス説明
400不正なリクエスト無効なリクエストパラメータ
401認証エラーAPIキーが欠落または無効
403禁止アクセス拒否またはプラン制限に達しました
404未発見リソースが存在しません
415サポートされていないメディアタイプ不正なContent-Typeヘッダー
422処理できないエンティティリクエストの形式は正しいものの実行できない。例：準備完了のMindsが10未満のオーディエンスで検証を開始した場合（AUDIENCE_TOO_SMALL）
429リクエストが多すぎますレート制限を超えました

5xx サーバーエラー

コードステータス説明
500サーバー内部エラーサーバー側のエラー
503サービス利用不可サービスが一時的に利用できません

一般的なエラー

400 不正なリクエスト

必須フィールドが欠落しています:

{
  "statusCode": 400,
  "statusMessage": "Name is required"
}

無効な入力:

{
  "statusCode": 400,
  "statusMessage": "File too large: document.pdf (55.2MB). Maximum size is 50MB."
}

401 認証エラー

APIキーが欠落しています:

{
  "statusCode": 401,
  "statusMessage": "Unauthorized"
}

解決策: Authorizationヘッダーを含めてください：

-H "Authorization: Bearer minds_your_api_key"

403 禁止

プラン制限に達しました:

{
  "statusCode": 403,
  "statusMessage": "Starter plan limit reached",
  "message": "Starter plan limit reached",
  "url": "/api/v1/minds",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

アクセス拒否:

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

404 未発見

リソースが存在しません:

{
  "statusCode": 404,
  "statusMessage": "Mind not found"
}

415 サポートされていないメディアタイプ

不正なContent-Type:

{
  "statusCode": 415,
  "statusMessage": "Unsupported Content-Type. Use application/json for links or multipart/form-data for files"
}

解決策: 正しいContent-Typeヘッダーを使用してください：

  • application/jsonはJSONリクエスト用
  • multipart/form-dataはファイルアップロード用

429 リクエストが多すぎます

レート制限を超えました:

{
  "statusCode": 429,
  "statusMessage": "Too many requests. Please try again later."
}

レート制限

v1 APIは認証済みアカウントごとの固定ウィンドウ制限を適用します。デプロイ時の既定値は1分あたり300リクエストですが、設定で変更できます。RateLimit-LimitとRateLimit-Remainingを確認し、429の後はRetry-Afterで指定された秒数だけ待機してください。

プラン制限

現在の公開デフォルト値は、生成されたプラン制限表を参照してください。契約固有のオーバーライドは異なる場合があるため、認証済みエラーのdata.limitとdata.currentがそのリクエストの正しい値です。StarterプランはAPI payloadでは"premium"と表示されます。

Mind制限の例

制限に達した際のエラー:

{
  "statusCode": 403,
  "statusMessage": "Starter plan limit reached",
  "message": "Starter plan limit reached",
  "url": "/api/v1/minds",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

知識アップロード制限

  • ファイルサイズ: 最大50MB（すべてのプラン）
  • ストレージ: 現在明示的なストレージ制限は施行されていません

APIキー制限

  • 最大キー数: 現在、上限は設けられていません。

オーディエンス検証の失敗

準備が完了したMindsが10未満のオーディエンスでオーディエンス検証を開始すると、コードAUDIENCE_TOO_SMALLとともに422が返されます。プランで1つの調査に使える規模を超えるオーディエンスは、上記の標準的なプラン制限エラーで拒否されます。

開始に成功すると検証はバックグラウンドで実行されるため、ほとんどの失敗はHTTPエラーにはなりません。代わりに、検証バッチのfailureフィールドを確認してください。バッチは次のいずれかのコードで終了することがあります。

コード意味
AUDIENCE_TOO_SMALLオーディエンスの準備完了のMindsが10未満です。検証の開始時には422としても返されます
MINDS_NEED_RETRAINING回答する前に、オーディエンス内のMindsの再トレーニングが必要です
NOT_ENOUGH_QUESTIONSオーディエンスに適合する質問が8問未満のため、何も質問されませんでした
NOT_ENOUGH_RESPONSES実行に必要な合成回答が、残りの数を上回っています
NO_FITTING_SURVEYオーディエンスに合う公表済みサーベイがありません
NO_USABLE_SURVEYこのオーディエンスを検証できるサーベイがありません
NO_SCOREこのオーディエンスについてスコア化できたサーベイがありません
RUNS_REFUSED検証の実行を開始できませんでした
SURVEY_NOT_FOUND指定されたサーベイが見つかりません
SURVEY_FILES_UNREADABLEアップロードされたサーベイファイルを読み取れません
SURVEY_RESULTS_NOT_FOUNDアップロードされたファイルに、比較できる公表結果が含まれていません
VALIDATION_TOO_LARGE検証で必要な回答が30,000件を超えます

ベストプラクティス

エラー処理

常にエラーを処理してください:

async function requestJson(url, apiKey, data) {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  const text = await response.text();
  let result = null;
  if (text) {
    try {
      result = JSON.parse(text);
    } catch {
      if (response.ok) throw new Error('Expected a JSON response');
    }
  }
  if (!response.ok) {
    throw Object.assign(new Error(result?.statusMessage || result?.message || `HTTP ${response.status}`), {
      status: response.status,
      data: result?.data,
      retryAfter: response.headers.get('Retry-After')
    });
  }
  return result;
}

リトライロジック

スマートなリトライを実装してください:

  • 一時的な 429 または 5xx 応答では、回数を制限した指数バックオフで読み取りを再試行し、Retry-After に従ってください。書き込みはエンドポイントが冪等性を保証する場合に限り、同じキーとリクエスト本文で再試行します。結果が不明なタイムアウト後は、再送信する前に既存のリソースやジョブを確認してください。
  • 指数バックオフを使用
  • 最大リトライ試行回数を設定
  • 4xxエラーではリトライしない（429を除く）

モニタリング

使用状況を追跡してください:

  • レート制限ヘッダーをログに記録
  • エラー率を監視
  • 繰り返し発生するエラーのアラートを設定
  • 応答時間を追跡

必要に応じてアップグレード

以下の場合はプランをアップグレードしてください：

  • レート制限に頻繁に達する
  • より多くのMindsが必要
  • より大きなファイルアップロードが必要
  • 優先サポートを希望

プランを見る

ヘルプを得る

ステータスを確認

サービスのステータスを監視してください：

サポートに連絡

以下の問題が発生した場合：

  • 持続的な500エラー
  • 不正確なレート制限
  • 予期しない動作

ご連絡ください：

ドキュメントを確認

ステータスコードリファレンス

すべてのHTTPステータスコードのクイックリファレンス：

2xx Success
├─ 200 OK
└─ 201 Created

4xx Client Error
├─ 400 Bad Request
├─ 401 Unauthorized
├─ 403 Forbidden
├─ 404 Not Found
├─ 415 Unsupported Media Type
└─ 429 Too Many Requests

5xx Server Error
├─ 500 Internal Server Error
└─ 503 Service Unavailable
Minds© 2026 Minds. あなたのターゲットオーディエンス。AIを活用し、透明な根拠に基づいています。数分で構築できます。
Minds は以下に参加しています
ESOMARGreenBookInsight PlatformsCapterraG2CSSDA Best UX Design AwardCSSDA Best Innovation AwardCSSDA Best UI Design Award