обработка ошибок веб-IQ Microsoft

Все API версии 3 возвращают стандартизированные ответы на ошибки, чтобы быстро диагностировать и устранять проблемы. В этом разделе рассматриваются коды состояния HTTP, структура ответа об ошибках и распространенные сценарии устранения неполадок.

Note

Все значения перечисления строк являются нечувствительными к регистру.

Коды состояния HTTP

Код состояния	Применимо к	Категория ошибки	Description	Распространенные причины
200	Все API	Success	Запрос был выполнен успешно.	-
202	Только обзор	Акцептировано	Запрос, принятый для обработки (динамический обход).	Выполняется обход по запросу
400	Все API	ошибка запроса	Недопустимые параметры запроса.	Отсутствующие обязательные поля, недопустимые значения параметров, некорректный JSON
401	Все API	Unauthorized	Сбой проверки подлинности или отсутствие.	Недопустимый ключ API, отсутствующий заголовок x-apikey
403	Все API	Forbidden	Допустимые учетные данные, но недостаточно разрешений.	Ключ API не имеет необходимых разрешений
403	Только обзор	Forbidden	Содержимое, отфильтрованное или исключенное URL-адрес.	URL-адрес, заблокированный политикой или содержимым, отфильтрованным
404	Только обзор	Не найдено	Документ не найден.	Недопустимый или недоступный URL-адрес
410	Все API	Отсутствует (Gone)	Требуется ПРОТОКОЛ HTTPS.	Запрос, сделанный по протоколу HTTP вместо HTTPS
415	Все API	Неподдерживаемый тип носителя	Тип контента не поддерживается.	Отсутствующий или неправильный content-type заголовок
429	Все API	Слишком много запросов	Превышено ограничение скорости.	Слишком много запросов в период времени
430	Только обзор	Ошибка сервера	Слишком много обходов по запросу.	Чрезмерные запросы динамического обхода
500	Все API	Внутренняя ошибка сервера	Непредвиденная ошибка сервера.	Проблема с временным сервером

Структура ответа об ошибках

Все ответы на ошибки соответствуют этой схеме:

Field	Type	Description
errorCode	string	Более подробная категория ошибок, которая помогает определить тип ошибки.
errorCategory	string	Высокоуровневая категория: UserError (клиентская или неизменяемая для повторных попыток) или (серверная или SystemError повторная попытка).
userMessage	string	Описание ошибки в понятном для человека формате.
technicalDetails	строка (необязательно)	Дополнительные технические сведения или сведения о проверке параметров для отладки.
retryAfter	строка (необязательно)	Время ожидания перед повтором.
requestId	строка (необязательно)	Уникальный идентификатор запроса.
traceId	string	Идентификатор распределенной трассировки для отладки и поддержки Microsoft.

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-DebugOptionsX-XapHostOverride). Вместо этого используйте параметры задокументированного URL-адреса (?p1=, ?debugoptions=, ?atlahostname=).
RequestUnsupportedMediaType	415	UserError	Заголовок content-type отсутствует или нет application/json.
MethodNotAllowed	405	UserError	Метод HTTP не разрешен для маршрута (например, GET в конечной точке только для POST).

Ошибки проверки подлинности и авторизации

Код ошибки	Состояние HTTP	Category	Description
AuthNoToken	401	UserError	Требуется проверка подлинности. Маркер носителя или ключ API не указан.
AuthTokenParse	401	UserError	Недопустимый формат маркера проверки подлинности или синтаксический анализ маркера завершился ошибкой.
AuthInvalidApiKey	401	UserError	Указанный ключ API недопустим или не распознается.
AuthenticationFailed	401	UserError	Общий сбой проверки подлинности.
AuthExpiredTrial	401	UserError	Срок пробной версии истек. Обновите ключ.
AuthMissingEntryId	400	UserError	Отсутствует удостоверение приложения / идентификатор записи в контексте запроса.
AuthAppIdSelectionRequired	400	UserError	Удостоверение сопоставляется с несколькими приложениями. Укажите целевое приложение с помощью APPID параметра запроса. Ознакомьтесь с вызовом нескольких идентификаторов appID.
AuthUnauthorizedEntryId	401	UserError	Несанкционированный идентификатор записи. Удостоверение приложения не удалось устранить, или APPID параметр запроса был отправлен с проверкой подлинности ключа API.
AuthUnauthorizedAppId	403	UserError	Указанный параметр APPID не связан с удостоверением.
AuthUnauthorizedService	403	UserError	Вызывающий объект проходит проверку подлинности, но несанкционированный доступ к запрошенной службе или вертикали.
AuthBatchEndpointRequired	403	UserError	Приложение требуется для использования пакетной конечной точки (X-FD-Batch: 1) для поиска в Интернете.
AuthMcpWebForbidden	403	UserError	Приложению не разрешено использовать средство MCP web .
AuthContentFormatForbidden	403	UserError	Это приложение имеет доступ только к проходам. Используйте contentFormatpassage. См. фрагменты и форматы содержимого.

Ошибки ограничения скорости

Код ошибки	Состояние 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. Ограничение скорости отображается на портале веб-IQ.

Решения:

• Реализуйте логику повторных попыток с экспоненциальной задержкой
• retryAfter Дождитесь интервала в ответе об ошибке (например, "60s") перед повтором
• Уменьшение частоты запросов
• Обратите внимание, что ежедневные ограничения квот (AuthUserDailyUsageExceeded) сбрасываются ежедневно в 00:00 UTC
• Чтобы запросить более высокое ограничение, обратитесь в службу поддержки веб-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 возвращает значение 202 Accepted со retryAfter значением, указывающим, когда повторить запрос.

Обработка:

# 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

Лучшие практики

1. Всегда проверяйте коды состояния . Не предполагайте успешность
2. Использование traceId для поддержки — включение traceId при обращении в службу поддержки
3. Реализация логики повторных попыток . Использование экспоненциального обратного выхода для временных ошибок
4. Обработка ответов 202 . Для просмотра API с помощью динамического обхода, ожидания и повтора
5. Проверка перед отправкой . Проверьте параметры локально, чтобы избежать 400 ошибок
6. Использовать только HTTPS . HTTP-запросы возвращают 410 ошибок