すべての v3 API は、問題を迅速に診断して解決するのに役立つ標準化されたエラー応答を返します。 このセクションでは、HTTP 状態コード、エラー応答構造、および一般的なトラブルシューティング シナリオについて説明します。
Note
すべての文字列列挙値では、大文字と小文字が区別されません。
HTTP 状態コード
| 状態コード | 適用対象 | エラー カテゴリ | Description | 一般的な原因 |
|---|---|---|---|---|
| 200 | すべての API | 成功 | 要求は成功しました。 | - |
| 202 | 参照のみ | 承認済み | 処理を受け入れた要求 (ライブ クロール)。 |
liveCrawlが "フォールバック" の場合に進行中のオンデマンド クロール |
| 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 | サーバー内部エラー | 予期しないサーバー エラー。 | 一時的なサーバーの問題 |
| 520 | 参照のみ | コンテンツ処理に失敗しました | ページが取得されましたが、使用可能なコンテンツを生成できませんでした。 | ドキュメントの処理に失敗したかタイムアウトしたか、動的レンダリングがタイムアウトしました |
| 523 | 参照のみ | クロールが取り消されました | サイト のクロール クォータが制限されているため、クロールが成功しなかったため、URL はコンテンツを生成しませんでした。 | ソース ホストの制限付きクロール クォータ |
| 524 | 参照のみ | クロール タイムアウト | クロールがタイムアウトしたため、URL はコンテンツを生成しませんでした。 | リモート ホストがタイムアウトしました |
状態 520、523、および 524 は、既定で有効になっている 詳細な参照エラー コードの一部です。
エラー応答の構造
すべてのエラー応答は、次のスキーマに従います。
| Field | タイプ | Description |
|---|---|---|
errorCode |
文字列 | エラーの種類を識別するのに役立つ、より詳細なエラー カテゴリ。 |
errorCategory |
文字列 | 大まかなカテゴリ: UserError (クライアント側/再試行不可) または SystemError (サーバー側/再試行可能)。 |
userMessage |
文字列 | 人間が判読できるエラーの説明。 |
technicalDetails |
string (省略可能) | デバッグのための追加の技術情報またはパラメーター検証の詳細。 |
retryAfter |
string (省略可能) | 再試行ガイダンス。
AuthUserThrottled、AuthUserDailyUsageExceeded、およびInternalServerErrorの場合、"s"サフィックスを持つ期間 (たとえば、"60s")。
TooManyOnDemandCrawls (429) を含む詳細なエラーを参照する場合は、再試行する最も早い時刻である ISO 8601 UTC タイムスタンプ (たとえば、"2026-10-30T01:01:00Z") です。 再試行ガイダンスが適用されない場合は省略されます。 |
requestId |
string (省略可能) | 要求の一意識別子。 |
traceId |
文字列 | デバッグとMicrosoftサポートのための分散トレース ID。 |
Note
retryAfter は 2 つの形式を使用します。
AuthUserThrottled、 AuthUserDailyUsageExceeded、および InternalServerError 応答では、 "60s"などの期間が使用されます。
202 Accepted応答を参照し、詳細なエラーを参照するには、絶対 ISO 8601 UTC タイムスタンプ ("2026-10-30T01:01:00Z" など) を使用します。 HTTP 状態だけでは形式が決まらない: TooManyOnDemandCrawls は 429 を返しますが、タイムスタンプを使用します。 再試行ロジックでは、両方の形式を処理する必要があります。
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]、無効な列挙値)。 参照継代要求の場合、 query が見つからない、空白、または 1000 文字を超える。 |
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 |
要求の頻度が AppID のレート制限を超えています。
retryAfterを確認します。 |
AuthUserDailyUsageExceeded |
429 | UserError |
日次要求クォータに達しました (00:00 UTC にリセット)。
retryAfterを確認します。 |
API 固有のエラーを参照する
詳細なエラー コードは、[参照] で既定で有効になっています。 コンテンツのフィルター処理、ドキュメントの不足、クロールの失敗など、ページが返されなかった具体的な理由を特定し、必要に応じて再試行ガイダンスを含めます。 オプトインまたはサポート要求は必要ありません。
詳細なコードとレガシ コードでは、標準の エラー応答構造が使用されます。 ここに記載されていない参照エラーは、 InternalServerError (HTTP 500) として報告されます。
従来の参照エラー コード
これらのコードは、詳細なエラー コードが既定になる前に使用されていました。 古い応答を処理するときに参照用に一覧表示されます。
| エラー コード | HTTP の状態 | Category | Description |
|---|---|---|---|
BrowseApiDocNotFound |
404 | UserError |
ドキュメントが見つかりません。 指定した URL に対して使用できるコンテンツはありません。 |
BrowseApiIsFilteredOut |
403 | UserError |
結果は、コンテンツ ポリシー、成人フィルター処理、アクセス制限、またはドメイン制限によって削除されました。 |
BrowseApiIsUrlExcluded |
403 | UserError |
ターゲット URL は、robots.txt またはクロールの除外ポリシーによって除外されます。 |
BrowseApiTooManyOnDemandCrawls |
430 | UserError |
進行中のオンデマンドのライブ クロール要求が多すぎます。 ライブ クロール率を下げる。 |
詳細な参照エラー コード
| エラー コード | HTTP の状態 | Category | 一般的な retryAfter |
userMessage |
推奨されるアクション |
|---|---|---|---|---|---|
InvalidUrl |
400 | UserError |
省略 | 要求された URL が無効です。 | 再試行する前に URL を修正します。 |
NotSupported |
400 | UserError |
省略 | 要求された URL はサポートされていません。 | サポートされている Web ドキュメントを指す URL を使用します。 |
URLFilteredOutSpamAdult |
403 | UserError |
約 24 時間 | 要求された URL は、スパムまたは成人のポリシーによってフィルター処理されました。 | ページを返すことはできません。
retryAfterする前に再試行しないでください。 |
URLFilteredOutEncumbrance |
403 | UserError |
約 24 時間 | 要求された URL は、コンテンツ制限によってフィルター処理されました。 | ロボット ディレクティブやペイウォール ルールなどの発行元またはサイト ポリシーでは、コンテンツの返却は許可されません。
retryAfterする前に再試行しないでください。 |
URLFilteredOutSource403Forbidden |
403 | UserError |
約 24 時間 | ソースが要求された URL へのアクセスを拒否しました。 | ソース サイトから HTTP 403 が返されました。
retryAfterする前に再試行しないでください。 |
BrowseApiIsFilteredOut |
403 | UserError |
約24時間、供給時 | 要求された URL がフィルターで除外されました。 | 特定のコードが含まない理由でページがフィルター処理されたときに返されます。
retryAfterする前に再試行しないでください。 |
DocNotFound |
404 | UserError |
クロール サービスによって指定されていない限り、省略されます | 要求されたドキュメントが見つかりませんでした。 | URL を確認するか、 liveCrawl を "フォールバック" に設定してライブ クロールを要求します。 |
TooManyOnDemandCrawls |
429 | UserError |
クロール サービスによって提供された場合 | 要求されたオンデマンド クロールが多すぎます。 | ライブ クロール率を下げる。
retryAfterが存在する場合は、その時刻まで待ってから再試行してください。 |
FailedNoContent |
520 | SystemError |
約 5 分 | ドキュメントの処理または発行で、使用可能なコンテンツを生成できませんでした。 |
retryAfter後に再試行してください。 |
DynamicRenderingTimeout |
520 | SystemError |
約 5 分 | 動的ページ レンダリングがタイムアウトしました。 |
retryAfter後に再試行するか、renderDynamicPagesせずに再試行します。 |
ProcessingTimeout |
520 | SystemError |
約 5 分 | ドキュメント処理がタイムアウトしました。 |
retryAfter後に再試行してください。 |
PolitenessCancellation |
523 | SystemError |
約 5 分 | ソース ホストのクロール制限を考慮してクロールが取り消されました。 | サイト のクロール クォータが制限されているため、クロールが成功しなかったため、URL はコンテンツを生成しませんでした。
retryAfter後に再試行してください。 |
HostCrawlTimeout |
524 | SystemError |
約 5 分 | ソース ホストのクロールがタイムアウトしました。 | クロールがタイムアウトしたため、URL でコンテンツが生成されませんでした。リモート ホストが時間内に応答しませんでした。
retryAfter後に再試行してください。 |
再試行の遅延が適用されると、応答には ISO 8601 UTC タイムスタンプとして retryAfter が yyyy-MM-ddTHH:mm:ssZ形式 ( "retryAfter": "2026-10-30T01:01:00Z"など) として含まれます。 その前に再試行しないでください。
retryAfterを省略すると、再試行ガイダンスは適用されません。
詳細なエラー応答の例:
{
"errorCode": "URLFilteredOutEncumbrance",
"errorCategory": "UserError",
"userMessage": "The requested URL was filtered by content restrictions.",
"retryAfter": "2026-10-31T01:00:00Z",
"traceId": "0123456789abcdef0123456789abcdef"
}
通過エラーを参照する
これらのエラーは、"passage" が既定の形式である、完全なドキュメント アクセスのないアプリケーションからの要求を含む、 contentFormat: "passage"で要求を参照する場合に適用されます。 「 通過要求の参照」を参照してください。
| 状態 | エラー コード | HTTP の状態 | userMessage |
|---|---|---|---|
query 不足、空、空白のみ、または 1000 文字を超える |
HandlerInvalidInput |
400 | 入力が無効です。 要求パラメーターを確認してください。 |
text、html、または完全なドキュメント アクセス要求がないアプリケーションmarkdown |
AuthContentFormatForbidden |
403 | このアプリケーションは、通路にのみアクセスできます。 contentFormat 'passage' を使用します。 |
通過要求の他のすべての参照結果では、 text、 html、および markdown 要求と同じ状態コードとエラー コードが使用されます。 これには、フィルター処理されたページ、ドキュメントが見つからない、保留中のライブ クロール (202 Accepted)、クロールエラーが含まれます。
サービスとインフラストラクチャのエラー
| エラー コード | 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)
AppID のレート制限を超える要求では、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)
現象: 応答本文に url フィールドと retryAfter フィールドがある承認済み応答 (202)
説明:liveCrawlが "フォールバック" で、URL がインデックスに見つからない場合、API は非同期的にクロールを開始し、202 Accepted を返すことができます。 ライブ クロールは、発行元の丁寧性の制限と可用性の対象となります。"フォールバック" では、実際のクロールは保証されません。
passageを含むすべてのcontentFormatにも同じ動作が適用されます。
取り扱い:
- HTTP 状態 202 を確認します。
- 応答本文から
retryAfterを読み取る。 これは、再試行する最も早い時刻である ISO 8601 UTC タイムスタンプ (たとえば、"2026-10-30T01:01:00Z") です。 - その時刻まで待ちます。
- 同じ要求をもう一度送信します。
urlフィールドには、要求する URL が含まれています。既定では、要求した URL が使用されます。 - ポーリングの試行回数を制限します。 完了できないクロールでは、最終的に
HostCrawlTimeout(524) やFailedNoContent(520) などのエラーが返されます。
# 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", "contentFormat": "passage", "query": "information about this domain", "liveCrawl": "fallback"}'
# Example response when the URL isn't indexed: 202 Accepted with "retryAfter": "2026-10-30T01:01:00Z"
# Wait until that time, then send the same request again
ベスト プラクティス
- 常に状態コードを確認 する - 成功を想定しない
- サポートに traceId を使用する - サポート に連絡するときに traceId を含める
- 再試行ロジックを実装 する - 一時的なエラーに指数バックオフを使用する
-
202 応答を処理する - ライブ クロールを使用する Browse API の場合は、
retryAfter時刻まで待ってから再試行します -
retryAfter形式の両方を処理する -AuthUserThrottled、AuthUserDailyUsageExceeded、およびInternalServerErrorの期間と、Browse 202 の ISO 8601 タイムスタンプと、TooManyOnDemandCrawls(429) を含む詳細なエラーを使用します - 送信前に検証 する - 400 エラーを回避するためにパラメーターをローカルで確認する
- HTTPS のみを使用 する - HTTP 要求は 410 エラーを返します