--- title: "エラーと制限" description: "APIエラー、ステータスコード、プランベースのリソース制限を理解する。" --- # エラーと制限 APIエラー、レート制限、プラン制限を理解する。 ## エラー応答フォーマット すべてのエラーは一貫したフォーマットに従います： ```json { "statusCode": 400, "statusMessage": "Name is required", "message": "Name is required", "url": "/api/v1/minds", "error": true } ```
フィールド 説明
statusCode HTTPステータスコード
statusMessage 人間が読み取れるエラー説明（ハンドラーによってエラーごとに設定されます - 検証エラーの場合、これは特定の問題です。例： "Mind not found" または "Invalid Mind ID format" ）
message v1エラーのための statusMessage と同じ内容。デバッグビルドの 5xx 応答におけるスタック/追加コンテキスト用に予約されています。
url リクエストパス（Nuxt H3によって追加されます）
error エラー応答のための true （Nuxt H3によって追加されます）
> プログラムによる処理には常に`statusCode`を頼りにし、人間が読み取れる理由には`statusMessage`（または`message`）を使用してください。`url`および`error`フィールドは、基盤となるフレームワークからの便利なメタデータです。 ## HTTPステータスコード ### 2xx 成功
コード ステータス 説明
200 OK リクエスト成功
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ヘッダー
429 リクエストが多すぎます レート制限を超えました
### 5xx サーバーエラー
コード ステータス 説明
500 サーバー内部エラー サーバー側のエラー
503 サービス利用不可 サービスが一時的に利用できません
## 一般的なエラー ### 400 不正なリクエスト **必須フィールドが欠落しています:** ```json { "statusCode": 400, "statusMessage": "Name is required" } ``` **無効な入力:** ```json { "statusCode": 400, "statusMessage": "File too large: document.pdf (55.2MB). Maximum size is 50MB." } ``` ### 401 認証エラー **APIキーが欠落しています:** ```json { "statusCode": 401, "statusMessage": "Unauthorized" } ``` **解決策:** `Authorization`ヘッダーを含めてください： ```bash -H "Authorization: Bearer minds_your_api_key" ``` ### 403 禁止 **プラン制限に達しました:** ```json { "statusCode": 403, "statusMessage": "Individual plan limit reached", "message": "Individual plan limit reached", "url": "/api/v1/minds", "error": true, "data": { "code": "PLAN_LIMIT", "limitType": "sparks", "currentPlan": "premium", "limit": 100, "current": 100 } } ``` **アクセス拒否:** ```json { "statusCode": 403, "statusMessage": "Access denied" } ``` ### 404 未発見 **リソースが存在しません:** ```json { "statusCode": 404, "statusMessage": "Mind not found" } ``` ### 415 サポートされていないメディアタイプ **不正なContent-Type:** ```json { "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 リクエストが多すぎます **レート制限を超えました:** ```json { "statusCode": 429, "statusMessage": "Too many requests. Please try again later." } ``` ## レート制限 v1 APIは認証済みアカウントごとの固定ウィンドウ制限を適用します。デプロイ時の既定値は1分あたり300リクエストですが、設定で変更できます。`RateLimit-Limit`と`RateLimit-Remaining`を確認し、`429`の後は`Retry-After`で指定された秒数だけ待機してください。 ## プラン制限 現在の公開デフォルト値は、生成された[プラン制限表](/docs/api/overview)を参照してください。契約固有のオーバーライドは異なる場合があるため、認証済みエラーの`data.limit`と`data.current`がそのリクエストの正しい値です。IndividualプランはAPI payloadでは`"premium"`と表示されます。 ### Mind制限の例 **制限に達した際のエラー:** ```json { "statusCode": 403, "statusMessage": "Individual plan limit reached", "message": "Individual plan limit reached", "url": "/api/v1/minds", "error": true, "data": { "code": "PLAN_LIMIT", "limitType": "sparks", "currentPlan": "premium", "limit": 100, "current": 100 } } ``` ### 知識アップロード制限 - **ファイルサイズ:** 最大50MB（すべてのプラン） - **ストレージ:** 現在明示的なストレージ制限は施行されていません ### APIキー制限 - **最大キー数:** 現在、上限は設けられていません。 ## ベストプラクティス ### エラー処理 **常にエラーを処理してください:** ```javascript try { const response = await fetch(url, { method: 'POST', headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' }, body: JSON.stringify(data) }); if (!response.ok) { const error = await response.json(); console.error(`Error ${error.statusCode}: ${error.message}`); // Handle specific errors if (error.statusCode === 429) { // Implement retry logic } } const result = await response.json(); return result; } catch (error) { console.error('Network error:', error); } ``` ### リトライロジック **スマートなリトライを実装してください:** - `429`（レート制限）および`5xx`エラーでリトライ - 指数バックオフを使用 - 最大リトライ試行回数を設定 - `4xx`エラーではリトライしない（429を除く） ### モニタリング **使用状況を追跡してください:** - レート制限ヘッダーをログに記録 - エラー率を監視 - 繰り返し発生するエラーのアラートを設定 - 応答時間を追跡 ### 必要に応じてアップグレード 以下の場合はプランをアップグレードしてください： - レート制限に頻繁に達する - より多くのMindsが必要 - より大きなファイルアップロードが必要 - 優先サポートを希望 [プランを見る](/settings?tab=subscription) ## ヘルプを得る ### ステータスを確認 サービスのステータスを監視してください： - [Mindsサービス稼働状況](https://uptime.getminds.ai) - 更新情報は[@mindsai_co](https://x.com/mindsai_co)をフォロー ### サポートに連絡 以下の問題が発生した場合： - 持続的な500エラー - 不正確なレート制限 - 予期しない動作 ご連絡ください： - フィードバックフォーム - メール: [support@getminds.ai](mailto:support@getminds.ai) ### ドキュメントを確認 - [API概要](/docs/api/overview) - [認証](/docs/api/authentication) - [Minds API](/docs/api/minds) - [Knowledge API](/docs/api/knowledge) - [Chat API](/docs/api/chat) ## ステータスコードリファレンス すべてのHTTPステータスコードのクイックリファレンス： ```text 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 ```