control de errores de Microsoft Web IQ

Todas las API v3 devuelven respuestas de error estandarizadas para ayudarle a diagnosticar y resolver problemas rápidamente. En esta sección se tratan los códigos de estado HTTP, la estructura de respuesta de errores y los escenarios comunes de solución de problemas.

Note

Todos los valores de enumeración de cadena no distinguen mayúsculas de minúsculas.

Códigos de estado HTTP

Código de estado	Se aplica a	Categoría de error	Description	Causas comunes
200	Todas las API	Success	La solicitud tuvo éxito.	-
202	Examinar solo	Aceptado	Solicitud aceptada para el procesamiento (rastreo en directo).	Rastreo a petición en curso
400	Todas las API	Solicitud incorrecta	Parámetros de solicitud no válidos.	Faltan campos obligatorios, valores de parámetro no válidos, JSON con formato incorrecto
401	Todas las API	Unauthorized	Error de autenticación o falta.	Clave de API no válida, falta el encabezado x-apikey
403	Todas las API	Prohibida	Credenciales válidas pero permisos insuficientes.	La clave de API carece de permisos necesarios
403	Examinar solo	Prohibida	Contenido filtrado o dirección URL excluido.	Dirección URL bloqueada por directiva o contenido filtrado
404	Examinar solo	No encontrado	No se encontró el documento.	Dirección URL no válida o inaccesible
410	Todas las API	Pasado (Gone)	SE requiere HTTPS.	Solicitud realizada a través de HTTP en lugar de HTTPS
415	Todas las API	Tipo de medio no admitido	No se admite el tipo de contenido.	Falta o encabezado incorrecto content-type
429	Todas las API	Demasiadas solicitudes	Se superó el límite de velocidad.	Demasiadas solicitudes en el período de tiempo
430	Examinar solo	Error del servidor	Demasiados rastreos a petición.	Solicitudes de rastreo en vivo excesivas
500	Todas las API	Error interno del servidor	Error inesperado del servidor.	Problema de servidor temporal

Estructura de respuesta a errores

Todas las respuestas de error siguen este esquema:

Field	Tipo	Description
errorCode	string	Categoría de error más detallada que ayuda a identificar el tipo de error.
errorCategory	string	Categoría de alto nivel: UserError (cliente/ no reintentos) o SystemError (servidor/reintentos).
userMessage	string	Descripción del error legible para el usuario.
technicalDetails	cadena (opcional)	Información técnica adicional o detalles de validación de parámetros para la depuración.
retryAfter	cadena (opcional)	Tiempo de espera antes de volver a intentarlo.
requestId	cadena (opcional)	Identificador único de la solicitud.
traceId	string	Identificador de seguimiento distribuido para la depuración y compatibilidad con Microsoft.

Note

202 Accepted las respuestas (por ejemplo, Examinar sondeo de rastreo activo) no son respuestas de error y no usan el esquema de error anterior. Todavía pueden incluir un retryAfter valor para indicar cuándo volver a intentar la solicitud.

Respuesta de error de ejemplo:

{
  "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"
}

Referencia de códigos de error

Errores de validación de solicitudes

Código de error	Estado HTTP	Category	Description
RequestInvalidFormat	400	UserError	Cuerpo JSON con formato incorrecto o estructura de carga de solicitud no válida.
RequestInvalidMethod	400	UserError	Nombre de herramienta o método no válido especificado en la solicitud.
HandlerInvalidInput	400	UserError	Valores de parámetros de entrada no válidos (por ejemplo, consulta vacía, maxResults fuera del intervalo [1, 50], valores de enumeración no válidos).
RequestBlockedHeader	400	UserError	La solicitud contiene un encabezado de depuración o variante en la lista de bloques (por ejemplo, X-Augmentations, X-DebugOptions, X-XapHostOverride). Use en su lugar parámetros de dirección URL documentados (?p1=, ?debugoptions=, ?atlahostname=).
RequestUnsupportedMediaType	415	UserError	Falta content-type el encabezado o no application/json.
MethodNotAllowed	405	UserError	No se permite el método HTTP en la ruta (por ejemplo, GET en un punto de conexión solo POST).

Errores de autenticación y autorización

Código de error	Estado HTTP	Category	Description
AuthNoToken	401	UserError	Se requiere autenticación. No se proporciona ningún token de portador ni clave de API.
AuthTokenParse	401	UserError	Error en el análisis de tokens de autenticación o formato de token no válido.
AuthInvalidApiKey	401	UserError	La clave de API proporcionada no es válida o no se reconoce.
AuthenticationFailed	401	UserError	Error general de autenticación.
AuthExpiredTrial	401	UserError	El período de prueba ha expirado. Actualice la clave.
AuthMissingEntryId	400	UserError	Falta la identidad de la aplicación o el identificador de entrada en el contexto de solicitud.
AuthAppIdSelectionRequired	400	UserError	La identidad se asigna a varias aplicaciones. Especifique la aplicación de destino mediante el APPID parámetro de consulta. Consulte Llamada a más de un AppID.
AuthUnauthorizedEntryId	401	UserError	Identificador de entrada no autorizado. No se pudo resolver la identidad de la aplicación o el parámetro de APPID consulta se envió con la autenticación de clave de API.
AuthUnauthorizedAppId	403	UserError	El especificado APPID no está asociado a la identidad.
AuthUnauthorizedService	403	UserError	El autor de la llamada se autentica pero no autorizado para acceder al servicio o vertical solicitados.
AuthBatchEndpointRequired	403	UserError	La aplicación es necesaria para usar el punto de conexión por lotes (X-FD-Batch: 1) para la búsqueda web.
AuthMcpWebForbidden	403	UserError	No se permite que la aplicación use la herramienta MCP web .
AuthContentFormatForbidden	403	UserError	Esta aplicación solo tiene acceso a los pasajes. Use contentFormatpassage. Consulte Pasajes y formatos de contenido.

Errores de limitación de velocidad

Código de error	Estado HTTP	Category	Description
AuthUserThrottled	429	UserError	La frecuencia de solicitud supera el límite de velocidad del recurso. Compruebe retryAfter.
AuthUserDailyUsageExceeded	429	UserError	Se ha alcanzado la cuota de solicitudes diarias (se restablece a las 00:00 UTC). Compruebe retryAfter.

Examinar errores específicos de la API

Código de error	Estado HTTP	Category	Description
BrowseApiDocNotFound	404	UserError	No se encontró el documento. No hay contenido disponible para la dirección URL especificada.
BrowseApiIsFilteredOut	403	UserError	El resultado se quitó debido al filtrado de directivas o contenido.
BrowseApiIsUrlExcluded	403	UserError	La directiva excluye o no permite la dirección URL de destino.
BrowseApiTooManyOnDemandCrawls	430	UserError	Hay demasiadas solicitudes de rastreo en vivo a petición en curso.

Errores de servicio e infraestructura

Código de error	Estado HTTP	Category	Se puede volver a intentar	Description
InternalServerError	500	SystemError	Sí (30s)	Error interno del servidor.

Escenarios de error habituales

Errores de autenticación (401, 403)

Síntoma: Error de autenticación o acceso prohibido

Soluciones:

• Compruebe que la clave de API es correcta e incluida en el x-apikey encabezado
• Compruebe que la clave de API no ha expirado
• Asegúrese de que tiene los permisos necesarios para el punto de conexión.
• Póngase en contacto con su representante de Microsoft si los problemas persisten

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"}'

Limitación de velocidad (429)

Síntoma: Límite de velocidad superado o cuota diaria agotada (AuthUserThrottled o AuthUserDailyUsageExceeded)

Las solicitudes anteriores al límite de velocidad del recurso devuelven HTTP 429. El límite de velocidad se muestra en el portal de Web IQ.

Soluciones:

• Implementación de la lógica de reintento de retroceso exponencial
• Espere al retryAfter intervalo en la respuesta de error (por ejemplo, "60s") antes de volver a intentarlo.
• Reducción de la frecuencia de solicitud
• Tenga en cuenta que los límites diarios de cuota (AuthUserDailyUsageExceeded) se restablecen diariamente a las 00:00 UTC.
• Para solicitar un límite mayor, póngase en contacto con el soporte técnico de Web IQ.

Respuesta de ejemplo:

{
  "errorCode": "AuthUserThrottled",
  "errorCategory": "UserError",
  "userMessage": "Rate limit exceeded. Please reduce your request frequency.",
  "retryAfter": "60s",
  "requestId": "req_123",
  "traceId": "trace_456"
}

Parámetros no válidos (400)

Síntoma: Solicitud incorrecta debido a parámetros no válidos

Problemas comunes:

• Faltan campos obligatorios (por ejemplo, query parámetro)
• Valores de parámetro fuera del intervalo (por ejemplo, maxResults> 50)
• Tipos de parámetros no válidos (por ejemplo, cadena en lugar de entero)
• Valores de parámetro no admitidos (por ejemplo, no válidos contentFormat)

Soluciones:

• Validar que todos los parámetros necesarios están presentes
• Comprobación de valores de parámetros con restricciones documentadas
• Garantizar el formato JSON adecuado

Errores de servidor e infraestructura (500)

Síntoma: Error inesperado del servidor interno o del servicio ascendente (InternalServerError)

Soluciones:

• Compruebe el retryAfter campo (el valor predeterminado es ) y vuelva a "30s"intentar la solicitud después de esperar.
• Implementación de reintentos con retroceso exponencial y vibración
• Si el problema persiste, póngase en contacto con Microsoft soporte técnico proporcionado traceId en la respuesta.

Respuesta de ejemplo:

{
  "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"
}

Examinar respuesta aceptada por la API (202)

Síntoma: Respuesta aceptada con retryAfter campo

Explicación: Cuando liveCrawl se establece en "reserva" y la dirección URL debe rastrearse, la API devuelve 202 Accepted con un retryAfter valor que indica cuándo reintentar la solicitud.

Manejo:

# 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

Prácticas recomendadas

1. Comprobar siempre los códigos de estado : no se supone que se ha realizado correctamente
2. Uso de traceId para soporte técnico : incluir traceId al ponerse en contacto con el soporte técnico
3. Implementación de la lógica de reintento : uso del retroceso exponencial para errores transitorios
4. Control de 202 respuestas : para Browse API con rastreo activo, espere y vuelva a intentarlo
5. Validar antes de enviar : compruebe los parámetros localmente para evitar errores 400.
6. Usar solo HTTPS : las solicitudes HTTP devolverán 410 errores