すべての v3 API は、問題を迅速に診断して解決するのに役立つ標準化されたエラー応答を返します。 このセクションでは、HTTP 状態コード、エラー応答構造、および一般的なトラブルシューティング シナリオについて説明します。
Note
すべての文字列列挙値では、大文字と小文字が区別されません。
HTTP 状態コード
| 状態コード | 適用対象 | エラー カテゴリ | Description | 一般的な原因 |
|---|---|---|---|---|
| 200 | すべての API | 成功 | 要求は成功しました。 | - |
| 202 | 参照のみ | 承認済み | 処理を受け入れた要求 (ライブ クロール)。 | 進行中のオンデマンド クロール |
| 400 | すべての API | 正しくない要求 | 要求パラメーターが無効です。 | 必須フィールドが見つからない、無効なパラメーター値、形式が正しくない JSON |
| 401 | すべての API | Unauthorized | 認証に失敗したか、見つかりません。 | 無効な API キー、x-apikey ヘッダーがありません |
| 403 | すべての API | 許可されていません | 有効な資格情報ですが、アクセス許可が不十分です。 | API キーに必要なアクセス許可がない |
| 403 | 参照のみ | 許可されていません | フィルター処理されたコンテンツまたは除外された URL。 | ポリシーまたはフィルター処理されたコンテンツによってブロックされる URL |
| 404 | 参照のみ | 見つかりません | ドキュメントが見つかりません。 | 無効またはアクセスできない URL |
| 410 | すべての API | 使用されていないリソース (Gone) | HTTPS が必要です。 | HTTPS ではなく HTTP 経由で行われた要求 |
| 415 | すべての API | サポートされていないメディアの種類 | コンテンツ タイプはサポートされていません。 | ヘッダー content-type 見つからないか正しくない |
| 429 | すべての API | 要求が多すぎます | レート制限を超えました。 | 時間枠内の要求が多すぎます |
| 430 | 参照のみ | サーバー エラー | オンデマンド クロールが多すぎます。 | 過剰なライブ クロール要求 |
| 500 | すべての API | サーバー内部エラー | 予期しないサーバー エラー。 | 一時的なサーバーの問題 |
エラー応答の構造
すべてのエラー応答は、次のスキーマに従います。
| Field | タイプ | Description |
|---|---|---|
errorCode |
文字列 | エラーの種類を識別するのに役立つ、より詳細なエラー カテゴリ。 |
errorCategory |
文字列 | 大まかなカテゴリ: UserError (クライアント側/再試行不可) または SystemError (サーバー側/再試行可能)。 |
userMessage |
文字列 | 人間が判読できるエラーの説明。 |
technicalDetails |
string (省略可能) | デバッグのための追加の技術情報またはパラメーター検証の詳細。 |
retryAfter |
string (省略可能) | 再試行する前に待機する時間。 |
requestId |
string (省略可能) | 要求の一意識別子。 |
traceId |
文字列 | デバッグとMicrosoftサポートのための分散トレース ID。 |
Note
202 Accepted 応答 (ライブ クロール ポーリングの参照など) はエラー応答ではなく、上記のエラー スキーマを使用しません。 要求を再試行するタイミングを示す retryAfter 値が引き続き含まれる場合があります。
エラー応答の例:
{
"errorCode": "HandlerInvalidInput",
"errorCategory": "UserError",
"userMessage": "Invalid input provided. Please check your request parameters.",
"technicalDetails": "Parameter validation failed: maxResults=100 exceeds maximum=50",
"requestId": "req_abc123",
"traceId": "trace_xyz789"
}
エラー コード リファレンス
要求の検証エラー
| エラー コード | HTTP の状態 | Category | Description |
|---|---|---|---|
RequestInvalidFormat |
400 | UserError |
形式が正しくない JSON 本文または無効な要求ペイロード構造。 |
RequestInvalidMethod |
400 | UserError |
要求で指定されたメソッドまたはツール名が無効です。 |
HandlerInvalidInput |
400 | UserError |
入力パラメーターの値が無効です (たとえば、空のクエリ、 maxResults 範囲外 [1, 50]、無効な列挙値)。 |
RequestBlockedHeader |
400 | UserError |
要求には、ブロックリスト化されたデバッグ/バリアント ヘッダー ( X-Augmentations、 X-DebugOptions、 X-XapHostOverrideなど) が含まれています。 代わりに、文書化された URL パラメーター (?p1=、 ?debugoptions=、 ?atlahostname=) を使用してください。 |
RequestUnsupportedMediaType |
415 | UserError |
content-type ヘッダーが見つからないか、application/jsonされていません。 |
MethodNotAllowed |
405 | UserError |
ルートでは HTTP メソッドが許可されていません (たとえば、POST 専用エンドポイントでの GET)。 |
認証と承認エラー
| エラー コード | HTTP の状態 | Category | Description |
|---|---|---|---|
AuthNoToken |
401 | UserError |
認証が必要です。 ベアラー トークンまたは API キーは指定されていません。 |
AuthTokenParse |
401 | UserError |
認証トークンの形式またはトークンの解析に失敗しました。 |
AuthInvalidApiKey |
401 | UserError |
指定された API キーが無効であるか、認識されていません。 |
AuthenticationFailed |
401 | UserError |
一般的な認証エラー。 |
AuthExpiredTrial |
401 | UserError |
試用期間の有効期限が切れています。 キーをアップグレードしてください。 |
AuthMissingEntryId |
400 | UserError |
要求コンテキストにアプリケーション ID/エントリ ID がありません。 |
AuthAppIdSelectionRequired |
400 | UserError |
ID は複数のアプリケーションにマップされます。
APPID クエリ パラメーターを使用して、ターゲット アプリケーションを指定します。
複数の AppID の呼び出しを参照してください。 |
AuthUnauthorizedEntryId |
401 | UserError |
未承認のエントリ ID。 アプリケーション ID を解決できなかったか、 APPID クエリ パラメーターが API キー認証で送信されました。 |
AuthUnauthorizedAppId |
403 | UserError |
指定した APPID が ID に関連付けされていません。 |
AuthUnauthorizedService |
403 | UserError |
呼び出し元は認証されていますが、要求されたサービス/垂直にアクセスすることは許可されていません。 |
AuthBatchEndpointRequired |
403 | UserError |
Web 検索にバッチ エンドポイント (X-FD-Batch: 1) を使用するには、アプリケーションが必要です。 |
AuthMcpWebForbidden |
403 | UserError |
アプリケーションで MCP web ツールを使用することはできません。 |
AuthContentFormatForbidden |
403 | UserError |
このアプリケーションは、通路にのみアクセスできます。
contentFormat
passageを使用します。 「 節とコンテンツの形式」を参照してください。 |
レート制限エラー
| エラー コード | HTTP の状態 | Category | Description |
|---|---|---|---|
AuthUserThrottled |
429 | UserError |
要求の頻度がリソースのレート制限を超えています。
retryAfterを確認します。 |
AuthUserDailyUsageExceeded |
429 | UserError |
日次要求クォータに達しました (00:00 UTC にリセット)。
retryAfterを確認します。 |
API 固有のエラーを参照する
| エラー コード | HTTP の状態 | Category | Description |
|---|---|---|---|
BrowseApiDocNotFound |
404 | UserError |
ドキュメントが見つかりません。 指定した URL に対して使用できるコンテンツはありません。 |
BrowseApiIsFilteredOut |
403 | UserError |
ポリシーまたはコンテンツのフィルター処理により、結果が削除されました。 |
BrowseApiIsUrlExcluded |
403 | UserError |
ターゲット URL は、ポリシーによって除外または禁止されます。 |
BrowseApiTooManyOnDemandCrawls |
430 | UserError |
進行中のオンデマンドのライブ クロール要求が多すぎます。 |
サービスとインフラストラクチャのエラー
| エラー コード | HTTP の状態 | Category | リトライ可能 | Description |
|---|---|---|---|---|
InternalServerError |
500 | SystemError |
はい (30 秒) | 内部サーバー エラーです。 |
一般的なエラー シナリオ
認証エラー (401、403)
現象: 認証に失敗したか、アクセスが禁止されました
ソリューション:
- API キーが正しく、
x-apikeyヘッダーに含まれていることを確認する - API キーの有効期限が切れていないことを確認する
- エンドポイントに必要なアクセス許可があることを確認します
- 問題が解決しない場合は、Microsoft担当者にお問い合わせください
Example:
# Correct authentication
curl -X POST "https://api.microsoft.ai/v3/search/web" \
-H "x-apikey: your-valid-key-here" \
-H "content-type: application/json" \
-d '{"query": "test"}'
レート制限 (429)
現象: レート制限を超えたか、日単位のクォータが使い果たされた (AuthUserThrottled または AuthUserDailyUsageExceeded)
リソースのレート制限を超える要求は HTTP 429 を返します。 レート制限は Web IQ ポータルに表示されます。
ソリューション:
- 指数バックオフ再試行ロジックを実装する
- 再試行する前に、エラー応答の
retryAfter間隔 (例:"60s") を待ちます - 要求の頻度を減らす
- 1 日あたりのクォータ上限 (
AuthUserDailyUsageExceeded) は毎日 00:00 UTC にリセットされることに注意してください - より高い制限を要求するには、Web IQ サポートにお問い合わせください
応答の例:
{
"errorCode": "AuthUserThrottled",
"errorCategory": "UserError",
"userMessage": "Rate limit exceeded. Please reduce your request frequency.",
"retryAfter": "60s",
"requestId": "req_123",
"traceId": "trace_456"
}
無効なパラメーター (400)
現象: パラメーターが無効なため、要求が正しくありません
一般的な問題:
- 必須フィールドがありません (例:
queryパラメーター) - パラメーター値が範囲外 (例:
maxResults> 50) - 無効なパラメーター型 (整数ではなく文字列など)
- サポートされていないパラメーター値 (無効な
contentFormatなど)
ソリューション:
- 必要なすべてのパラメーターが存在することを検証する
- 文書化された制約に対してパラメーター値を確認する
- 適切な JSON 形式を確認する
サーバーとインフラストラクチャのエラー (500)
現象: 予期しない内部サーバーまたはアップストリーム サービス エラー (InternalServerError)
ソリューション:
-
retryAfterフィールド (既定値は"30s") を確認し、待機後に要求を再試行します - 指数バックオフとジッターを使用して再試行を実装する
- 問題が解決しない場合は、Microsoftサポートに連絡し、応答で提供された
traceIdに問い合わせてください
応答の例:
{
"errorCode": "InternalServerError",
"errorCategory": "SystemError",
"userMessage": "The service is temporarily unavailable. Please try again later.",
"technicalDetails": "An internal service error occurred. Please contact support if the issue persists.",
"retryAfter": "30s",
"traceId": "trace_456"
}
API が受け入れた応答を参照する (202)
現象:retryAfter フィールドで受け入れられた応答
説明:liveCrawlが "フォールバック" に設定されていて、URL をクロールする必要がある場合、API は要求を再試行するタイミングを示すretryAfter値で 202 Accepted を返します。
取り扱い:
# Initial request
curl -X POST "https://api.microsoft.ai/v3/browse" \
-H "x-apikey: your-key" \
-H "content-type: application/json" \
-d '{"url": "https://example.com", "liveCrawl": "fallback"}'
# Response: 202 Accepted with retryAfter
# Wait for the specified time, then retry the same request
ベスト プラクティス
- 常に状態コードを確認 する - 成功を想定しない
- サポートに traceId を使用する - サポート に連絡するときに traceId を含める
- 再試行ロジックを実装 する - 一時的なエラーに指数バックオフを使用する
- 202 応答を処理する - ライブ クロールを使用する Browse API の場合は、待機して再試行します
- 送信前に検証 する - 400 エラーを回避するためにパラメーターをローカルで確認する
- HTTPS のみを使用 する - HTTP 要求は 410 エラーを返します