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.

La API de administración de clientes v1 usa estados de recursos autorizados independientes y códigos de estado de administración de ámbito y cuerpos de error.

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 cuando liveCrawl se "reserva"
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. En Examinar con códigos de error pormenorizados, también se devuelve cuando se solicitan demasiados rastreos a petición.	Demasiadas solicitudes en el período de tiempo o solicitudes de rastreo en vivo excesivas
430	Examinar solo	Error del servidor	Demasiados rastreos a petición (códigos de error heredados).	Solicitudes de rastreo en vivo excesivas
500	Todas las API	Error interno del servidor	Error inesperado del servidor.	Problema de servidor temporal
520	Examinar solo	Error de procesamiento de contenido	Se recuperó la página, pero no se pudo generar contenido utilizable.	Error en el procesamiento de documentos o se agota el tiempo de espera de la representación dinámica
523	Examinar solo	Rastreo cancelado	La dirección URL no produjo ningún contenido porque el rastreo no se realizó correctamente debido a una cuota limitada de rastreo del sitio.	Cuota de rastreo limitada para el host de origen
524	Examinar solo	Tiempo de espera de rastreo	La dirección URL no produjo ningún contenido porque se agotó el tiempo de espera del rastreo.	Se agota el tiempo de espera del host remoto.

Los estados 520, 523 y 524 forman parte de códigos de error granulares examinar, que están habilitados de forma predeterminada.

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)	Guía de reintento. Para AuthUserThrottled, AuthUserDailyUsageExceeded, InternalServerErrory ScopeFailedToApply, una duración con un "s" sufijo (por ejemplo, "60s"). Para Examinar errores pormenorizados, incluidos TooManyOnDemandCrawls (429), una marca de tiempo ISO 8601 UTC (por ejemplo, "2026-10-30T01:01:00Z") que es la primera vez que se reintenta. Se omite cuando no se aplica ninguna guía de reintento.
requestId	cadena (opcional)	Identificador único de la solicitud.
traceId	string	Identificador de seguimiento distribuido para la depuración y compatibilidad con Microsoft.

Note

retryAfter usa dos formatos. AuthUserThrottledLas respuestas , AuthUserDailyUsageExceeded, InternalServerErrory ScopeFailedToApply usan una duración como "60s". Examinar respuestas y Examinar 202 Accepted errores granulares usan una marca de tiempo ISO 8601 UTC absoluta, como "2026-10-30T01:01:00Z". El estado HTTP por sí solo no determina el formato: TooManyOnDemandCrawls devuelve 429, pero usa una marca de tiempo. La lógica de reintento debe controlar ambos formatos.

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. Incluyen una retryAfter marca de tiempo para indicar cuándo reintentar 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). En Examinar solicitudes de pasaje, query falta, está en blanco o más de 1000 caracteres.
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 de AppID. Compruebe retryAfter.
AuthUserDailyUsageExceeded	429	UserError	Se ha alcanzado la cuota de solicitudes diarias (se restablece a las 00:00 UTC). Compruebe retryAfter.

Errores de ámbito con nombre

Cuando scopeName se proporciona, failOnMissingScope el valor predeterminado es true, incluido cuando se omite o null. Si el servicio informa de que no se pudo aplicar el ámbito necesario, Web Search y News Search devuelven el siguiente estado HTTP y errorCode en la respuesta REST pública:

Condition	Código de error	Estado HTTP	Acción
La búsqueda de ámbito confirma que falta el ámbito con nombre.	HandlerInvalidInput	400	Compruebe el nombre, la cuenta de facturación de Web IQ AppID seleccionada y si el nuevo ámbito se ha propagado.
El ámbito no se puede aplicar por otro motivo, incluido un error de recuperación o una causa desconocida.	ScopeFailedToApply	500	Siga las instrucciones de reintento de la respuesta con retroceso limitado; póngase en contacto con el soporte técnico si el error persiste. No suponga que el nombre del ámbito no es válido.

Un ámbito recién creado puede faltar en la partición o réplica que controla la solicitud mientras la propagación está en curso. No cambie a failOnMissingScope: false simplemente para omitir un error si la aplicación requiere resultados con ámbito: false permite una búsqueda de todo el índice sin el ámbito.

Con false, se devuelve una aplicación incorrecta notificada como scopeApplied: false en la respuesta de búsqueda normal. Una aplicación correcta notificada es scopeApplied: true; cero documentos coincidentes no son un error de aplicación de ámbito. El campo se omite cuando no se notifica ningún resultado de la aplicación. Sin scopeName, failOnMissingScope no tiene ningún efecto.

Ni tampoco scopeApplied: truefailOnMissingScope: true garantiza que se haya usado la definición más reciente. Consulte comprobación e implementación del ámbito.

Examinar errores específicos de la API

Los códigos de error granulares están habilitados de forma predeterminada para Examinar. Identifican el motivo específico por el que no se pudo devolver una página, como el filtrado de contenido, un documento que falta o un error de rastreo, e incluyen instrucciones de reintento cuando corresponda. No se requiere ninguna solicitud de participación o soporte técnico.

Los códigos granulares y heredados usan la estructura de respuesta de error estándar. Los errores de exploración que no aparecen aquí se notifican como InternalServerError (HTTP 500).

Códigos de error de Exploración heredada

Estos códigos se usaron antes de que los códigos de error granulares se convirtieran en el valor predeterminado. Se muestran como referencia al controlar respuestas anteriores.

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ó mediante la directiva de contenido, el filtrado para adultos, las restricciones de acceso o las restricciones de dominio.
BrowseApiIsUrlExcluded	403	UserError	Las directivas de exclusión de rastreo o robots.txt excluyen la dirección URL de destino.
BrowseApiTooManyOnDemandCrawls	430	UserError	Hay demasiadas solicitudes de rastreo en vivo a petición en curso. Reduzca la velocidad de rastreo en vivo.

Códigos de error de exploración pormenorizados

Código de error	Estado HTTP	Category	Típico retryAfter	userMessage	Acción recomendada
InvalidUrl	400	UserError	Omitido	La dirección URL solicitada no es válida.	Corrija la dirección URL antes de volver a intentarlo.
NotSupported	400	UserError	Omitido	No se admite la dirección URL solicitada.	Use una dirección URL que apunte a un documento web compatible.
URLFilteredOutSpamAdult	403	UserError	Aproximadamente 24 horas	La dirección URL solicitada se filtre por correo no deseado o por directiva para adultos.	No se puede devolver la página. No vuelva a intentarlo antes retryAfterde .
URLFilteredOutEncumbrance	403	UserError	Aproximadamente 24 horas	La dirección URL solicitada se filtre por restricciones de contenido.	La directiva de editor o sitio, como directivas robots o reglas de pago, no permite que se devuelva el contenido. No vuelva a intentarlo antes retryAfterde .
URLFilteredOutSource403Forbidden	403	UserError	Aproximadamente 24 horas	El origen denegó el acceso a la dirección URL solicitada.	El sitio de origen devolvió HTTP 403. No vuelva a intentarlo antes retryAfterde .
BrowseApiIsFilteredOut	403	UserError	Aproximadamente 24 horas, cuando se suministra	La dirección URL solicitada se ha filtrado.	Se devuelve cuando se filtra una página por un motivo que no cubre ningún código más específico. No vuelva a intentarlo antes retryAfterde .
DocNotFound	404	UserError	Se omite, a menos que lo proporcione el servicio de rastreo.	No se encontró el documento solicitado.	Compruebe la dirección URL o establezca liveCrawl en "reserva" para solicitar un rastreo activo.
TooManyOnDemandCrawls	429	UserError	Cuando lo proporciona el servicio de rastreo	Se solicitaron demasiados rastreos a petición.	Reduzca la velocidad de rastreo en vivo. Si retryAfter está presente, espere hasta ese momento antes de volver a intentarlo.
FailedNoContent	520	SystemError	Unos 5 minutos	El procesamiento o la publicación de documentos no pudieron generar contenido utilizable.	Vuelva a intentarlo después retryAfterde .
DynamicRenderingTimeout	520	SystemError	Unos 5 minutos	Se agota el tiempo de espera de representación de páginas dinámicas.	Vuelva a intentarlo después retryAfterde o vuelva a intentarlo sin renderDynamicPages.
ProcessingTimeout	520	SystemError	Unos 5 minutos	Se agota el tiempo de espera del procesamiento de documentos.	Vuelva a intentarlo después retryAfterde .
PolitenessCancellation	523	SystemError	Unos 5 minutos	El rastreo se canceló para respetar los límites de rastreo del host de origen.	La dirección URL no produjo ningún contenido porque el rastreo no se realizó correctamente debido a una cuota limitada de rastreo del sitio. Vuelva a intentarlo después retryAfterde .
HostCrawlTimeout	524	SystemError	Unos 5 minutos	Se agota el tiempo de espera del rastreo del host de origen.	La dirección URL no produjo ningún contenido porque el rastreo agotó el tiempo de espera: el host remoto no respondió a tiempo. Vuelva a intentarlo después retryAfterde .

Cuando se aplica un retraso de reintento, la respuesta incluye retryAfter como marca de tiempo ISO 8601 UTC en el formato yyyy-MM-ddTHH:mm:ssZ, por ejemplo "retryAfter": "2026-10-30T01:01:00Z". No vuelva a intentarlo antes de ese tiempo. Cuando retryAfter se omite, no se aplica ninguna guía de reintento.

Respuesta de error granular de ejemplo:

{
  "errorCode": "URLFilteredOutEncumbrance",
  "errorCategory": "UserError",
  "userMessage": "The requested URL was filtered by content restrictions.",
  "retryAfter": "2026-10-31T01:00:00Z",
  "traceId": "0123456789abcdef0123456789abcdef"
}

Examinar errores de pasaje

Estos errores se aplican a Examinar solicitudes con contentFormat: "passage", incluidas las solicitudes de las aplicaciones sin acceso completo al documento, para las que "passage" es el formato predeterminado. Consulte Examinar solicitudes de paso.

Condition	Código de error	Estado HTTP	userMessage
query faltan, vacías, solo espacios en blanco o más de 1000 caracteres	HandlerInvalidInput	400	Entrada no válida proporcionada. Compruebe los parámetros de la solicitud.
Una aplicación sin solicitudes textde acceso a documentos completas, html, o markdown	AuthContentFormatForbidden	403	Esta aplicación solo tiene acceso a los pasajes. Use contentFormat 'passage'.

Todos los demás resultados examinar para las solicitudes de paso usan los mismos códigos de estado y códigos de error que textlas solicitudes , htmly markdown . Esto incluye páginas filtradas, documentos no encontrados, un rastreo activo pendiente (202 Accepted) y errores de rastreo.

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

Ejemplo:

# 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 por encima del límite de velocidad de AppID 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 (202) con url campos y retryAfter en el cuerpo de la respuesta

Explicación: Cuando liveCrawl es "reserva" y la dirección URL no se encuentra en el índice, la API puede iniciar un rastreo de forma asincrónica y devolver 202 Accepted. El rastreo en vivo está sujeto a restricciones y disponibilidad del publicador; "reserva" no garantiza un rastreo real. El mismo comportamiento se aplica a cada contentFormat, incluido passage.

Control:

1. Compruebe el estado HTTP 202.
2. Lee retryAfter del cuerpo de la respuesta. Es una marca de tiempo ISO 8601 UTC (por ejemplo, "2026-10-30T01:01:00Z") que es la primera vez que se reintenta.
3. Espere hasta ese momento.
4. Vuelva a enviar la misma solicitud. El url campo contiene la dirección URL que se va a solicitar; el valor predeterminado es la dirección URL que solicitó.
5. Limite el número de intentos de sondeo. Un rastreo que no se puede completar finalmente devuelve un error, como HostCrawlTimeout (524) o 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

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 respuestas 202 : para Browse API con rastreo activo, espere hasta el retryAfter momento y vuelva a intentarlo.
5. Controlar ambos retryAfter formatos : use la duración de AuthUserThrottled, AuthUserDailyUsageExceeded, InternalServerErrory ScopeFailedToApply, y la marca de tiempo ISO 8601 para Examinar 202 y errores granulares, incluidos TooManyOnDemandCrawls (429)
6. Validar antes de enviar : compruebe los parámetros localmente para evitar errores 400.
7. Usar solo HTTPS : las solicitudes HTTP devolverán 410 errores