Gestão de erros do Microsoft Web IQ

Todas as APIs v3 devolvem respostas de erro padronizadas para o ajudar a diagnosticar e resolver problemas rapidamente. Esta secção cobre códigos de estado HTTP, estrutura de resposta a erros e cenários comuns de resolução de problemas.

A API de Gestão de Clientes v1 utiliza estados de recursos autorizados e códigos de estado de gestão de âmbito e corpos de erro separados.

Note

Todos os valores de enum da cadeia são indiferentes a maiúsculas.

Códigos de status HTTP

Código de estado Aplica-se a Categoria de Erro Description Causas Comuns
200 Todas as APIs Sucesso O pedido foi bem-sucedido. -
202 Apenas navegar Aceito Pedido aceite para processamento (live crawl). Rastreamento on-demand em curso quando liveCrawl é "plano B"
400 Todas as APIs Pedido Incorreto Parâmetros de pedido inválidos. Campos obrigatórios em falta, valores de parâmetros inválidos, JSON mal formado
401 Todas as APIs Não autorizado Autenticação falhada ou em falta. Chave API inválida, falta do cabeçalho x-apikey
403 Todas as APIs Proibido Credenciais válidas mas permissões insuficientes. A chave API não tem as permissões necessárias
403 Apenas navegar Proibido Conteúdo filtrado ou URL excluído. URL bloqueado por política ou conteúdo filtrado
404 Todas as APIs Não encontrado Caminho não encontrado. Caminho de endpoint mal escrito ou não suportado
404 Apenas navegar Não encontrado Documento não encontrado. URL inválida ou inacessível
410 Todas as APIs Desapareceu HTTPS necessário. Pedido feito por HTTP em vez de HTTPS
415 Todas as APIs Tipo de Media Não Suportado Tipo de conteúdo não suportado. Cabeçalho em falta ou incorreto content-type
429 Todas as APIs Demasiados Pedidos Limite de taxa ultrapassado. Para o Browse com códigos de erro granulares, também é devolvido quando são solicitados muitos rastreamentos on-demand. Demasiados pedidos na janela temporal, ou pedidos excessivos de crawl ao vivo
430 Apenas navegar Erro do servidor Demasiadas explorações sob demanda (códigos de erro legados). Pedidos excessivos de rastreamento ao vivo
500 Todas as APIs Erro interno do servidor Erro inesperado do servidor. Problema temporário com o servidor
520 Apenas navegar Processamento de Conteúdo Falhou A página foi recuperada, mas não foi possível produzir conteúdo utilizável. O processamento de documentos falhou ou expirou, ou a renderização dinâmica expirou
523 Apenas navegar Crawl Cancelado O URL não produziu qualquer conteúdo porque o rastreamento não teve sucesso devido à quota limitada de rastreamento do site. Quota limitada de rastreamento para o host de origem
524 Apenas navegar Tempo de Descanso de Rastejar O URL não produziu qualquer conteúdo porque o rastreamento expirou. O host remoto expirou o tempo

Os estados 520, 523 e 524 fazem parte de códigos de erro granulares de navegação, que estão ativados por defeito.

Estrutura de Resposta a Erros

Todas as respostas ao erro seguem este esquema:

Field Tipo Description
errorCode cadeia (de caracteres) Uma categoria de erro mais detalhada que ajuda a identificar o tipo de erro.
errorCategory cadeia (de caracteres) Categoria de alto nível: UserError (lado do cliente / não retentável) ou SystemError (lado do servidor / retentável).
userMessage cadeia (de caracteres) Descrição do erro legível por humanos.
technicalDetails string (opcional) Informação técnica adicional ou detalhes de validação de parâmetros para depuração.
retryAfter string (opcional) Retentar orientação. Para AuthUserThrottled, AuthUserDailyUsageExceeded, InternalServerError, e ScopeFailedToApply, uma duração com um "s" sufixo (por exemplo, "60s"). Para erros granulares de navegação, incluindo TooManyOnDemandCrawls (429), um carimbo de data ISO 8601 UTC (por exemplo, "2026-10-30T01:01:00Z") que é o tempo mais cedo para tentar novamente. É omitido quando não se aplica nenhuma orientação de retentativa.
requestId string (opcional) Identificador único para o pedido.
traceId cadeia (de caracteres) ID de traço distribuído para depuração e suporte Microsoft.

Note

retryAfter utiliza dois formatos. AuthUserThrottled, AuthUserDailyUsageExceeded, , e ScopeFailedToApply as respostas usam uma duração como "60s"InternalServerError. Navegar 202 Accepted por respostas e Navegar por erros granulares utiliza um carimbo de hora absoluto ISO 8601 UTC, como "2026-10-30T01:01:00Z". O estado HTTP por si só não determina o formato: TooManyOnDemandCrawls devolve 429 mas usa um carimbo temporal. A lógica de retentativa deve lidar com ambos os formatos.

Note

202 Accepted as respostas (por exemplo, Browse live crawl polling) não são respostas de erro e não utilizam o esquema de erro acima. Incluem um retryAfter carimbo temporal para indicar quando tentar novamente o pedido.

Exemplo de Resposta a Erro:

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

Referência de Códigos de Erro

Erros de Validação de Pedidos

Código de Erro Estado HTTP Category Description
RequestInvalidFormat 400 UserError Corpo JSON mal formado ou estrutura de carga útil de pedido inválida.
RequestInvalidMethod 400 UserError Nome inválido do método ou ferramenta especificado no pedido.
HandlerInvalidInput 400 UserError Valores de parâmetros de entrada inválidos (por exemplo, consulta vazia, maxResults fora do intervalo [1, 50], valores de enum inválidos). Para pedidos de Navegação de passagem, query está em falta, em branco ou com mais de 1000 caracteres.
RequestBlockedHeader 400 UserError O pedido contém um cabeçalho de depuração/variante blocklist (por exemplo, X-Augmentations, X-DebugOptions, X-XapHostOverride). Use os parâmetros de URL documentados (?p1=, ?debugoptions=, ?atlahostname=) em vez disso.
RequestUnsupportedMediaType 415 UserError O content-type cabeçalho está em falta ou não application/json.
MethodNotAllowed 405 UserError O método HTTP não é permitido na rota (por exemplo, GET num endpoint apenas POST).

Erros de Autenticação e Autorização

Código de Erro Estado HTTP Category Description
AuthNoToken 401 UserError É necessária autenticação. Não é fornecido token portador nem chave API.
AuthTokenParse 401 UserError O formato ou análise de token de autenticação inválido falhou.
AuthInvalidApiKey 401 UserError A chave API fornecida é inválida ou não reconhecida.
AuthenticationFailed 401 UserError Falha geral de autenticação.
AuthExpiredTrial 401 UserError O período experimental expirou. Por favor, atualiza a tua chave.
AuthMissingEntryId 400 UserError Falta a identidade da aplicação / ID de entrada no contexto do pedido.
AuthAppIdSelectionRequired 400 UserError A sua identidade corresponde a múltiplas aplicações. Especifique a aplicação alvo usando o APPID parâmetro de consulta. Veja Chamar mais do que um AppID.
AuthUnauthorizedEntryId 401 UserError Identificação de entrada não autorizada. A identidade da aplicação não pôde ser resolvida, ou o APPID parâmetro de consulta foi enviado com autenticação por chave API.
AuthUnauthorizedAppId 403 UserError O especificado APPID não está associado à sua identidade.
AuthUnauthorizedService 403 UserError O chamador está autenticado, mas não autorizado a aceder ao serviço/vertical solicitado.
AuthBatchEndpointRequired 403 UserError A aplicação é obrigada a usar o endpoint batch (X-FD-Batch: 1) para pesquisa web.
AuthMcpWebForbidden 403 UserError A aplicação não é permitida para utilizar a ferramenta MCP web .
AuthContentFormatForbidden 403 UserError Esta aplicação só tem acesso a passagens. contentFormat passageUse . Ver Passagens e formatos de conteúdo.

Erros de limitação de taxa

Código de Erro Estado HTTP Category Description
AuthUserThrottled 429 UserError A frequência dos pedidos excede o limite de taxa do seu AppID. Verifique retryAfter.
AuthUserDailyUsageExceeded 429 UserError A quota diária de pedidos foi atingida (reinício às 00:00 UTC). Verifique retryAfter.

Erros de âmbito nomeado

Quando scopeName é fornecido, failOnMissingScope por defeito, é true, incluindo quando omitido ou null. Se o serviço reportar que o âmbito necessário não pôde ser aplicado, Web Search, News Search e Auto retornam o seguinte estado HTTP e errorCode , no público, a resposta REST:

Condition Código de erro Estado HTTP Action
A consulta pelo escopo confirma que o escopo nomeado está em falta. HandlerInvalidInput 400 Verifique o nome, a conta de faturação do AppID Web IQ selecionado e se o novo âmbito se propagou.
O endoscópio não pode ser aplicado por outra razão, incluindo uma falha na recolha ou uma causa desconhecida. ScopeFailedToApply 500 Siga as orientações de retentativa da resposta com recuo limitado; contacte o Suporte se a falha persistir. Não presuma que o nome do âmbito é inválido.

Um escopo recém-criado pode estar ausente da partição ou réplica que está a tratar do pedido enquanto a propagação está em andamento. Não mude para failOnMissingScope: false apenas contornar um erro se a sua aplicação exigir resultados com o âmbito: false permite uma pesquisa em todo o índice sem o escopo.

Com false, uma candidatura reportada e não bem-sucedida é devolvida como scopeApplied: false na resposta normal de pesquisa. Uma aplicação reportada bem-sucedida é scopeApplied: true; zero documentos correspondentes não são uma falha no âmbito da aplicação. O campo é omitido quando não é reportado o resultado da candidatura. Sem scopeName, failOnMissingScope não tem efeito.

Nem failOnMissingScope: true garante scopeApplied: true que a definição mais recente tenha sido usada. Veja verificação do âmbito e implementação.

Navegar por Erros Específicos da API

Códigos de erro granulares estão ativados por defeito para navegar. Identificam a razão específica pela qual uma página não pôde ser devolvida, como filtragem de conteúdo, um documento em falta ou uma falha de rastreamento, e incluem orientações para retentar quando aplicável. Não é necessário optar por aceitar ou pedir de Suporte.

Códigos granulares e antigos utilizam a estrutura padrão de resposta ao erro. Erros de navegação que não estão listados aqui são reportados como InternalServerError (HTTP 500).

Códigos de erro Legacy Browse

Estes códigos eram usados antes de os códigos de erro granulares se tornarem o padrão. Estão listados para referência ao lidar com respostas antigas.

Código de Erro Estado HTTP Category Description
BrowseApiDocNotFound 404 UserError Documento não encontrado. Não há conteúdo disponível para a URL especificada.
BrowseApiIsFilteredOut 403 UserError O resultado foi eliminado pela política de conteúdo, filtragem para adultos, restrições de acesso ou restrições de domínio.
BrowseApiIsUrlExcluded 403 UserError A URL alvo é excluída por políticas de exclusão de robots.txt ou crawl.
BrowseApiTooManyOnDemandCrawls 430 UserError Demasiados pedidos de rastreamento ao vivo em andamento. Reduz a taxa de rastreamento ao vivo.

Códigos de erro Granular Browse

Código de Erro Estado HTTP Category Típico retryAfter userMessage Ação recomendada
InvalidUrl 400 UserError Omitida O URL solicitado é inválido. Corrige o URL antes de tentar novamente.
NotSupported 400 UserError Omitida O URL solicitado não é suportado. Use uma URL que aponte para um documento web suportado.
URLFilteredOutSpamAdult 403 UserError Cerca de 24 horas O URL solicitado foi filtrado por spam ou política para adultos. A página não pode ser devolvida. Não tente novamente antes retryAfterde .
URLFilteredOutEncumbrance 403 UserError Cerca de 24 horas O URL solicitado foi filtrado por restrições de conteúdo. A política do editor ou do site, como diretivas de robôs ou regras de paywall, não permite que o conteúdo seja devolvido. Não tente novamente antes retryAfterde .
URLFilteredOutSource403Forbidden 403 UserError Cerca de 24 horas A fonte negou o acesso ao URL solicitado. O site de origem devolveu HTTP 403. Não tente novamente antes retryAfterde .
BrowseApiIsFilteredOut 403 UserError Cerca de 24 horas, quando fornecida O URL solicitado foi filtrado. Devolvem quando uma página é filtrada por uma razão que nenhum código mais específico cobre. Não tente novamente antes retryAfterde .
DocNotFound 404 UserError Omitido, a menos que seja fornecido pelo serviço de rastreamento O documento solicitado não foi encontrado. Verifique a URL, ou defina liveCrawl para "recurso" para solicitar um rastreamento ao vivo.
TooManyOnDemandCrawls 429 UserError Quando fornecida pelo serviço de rastreamento Foram pedidos demasiados crawls on-demand. Reduz a taxa de rastreamento ao vivo. Se retryAfter estiver presente, espere até esse momento antes de tentar novamente.
FailedNoContent 520 SystemError Cerca de 5 minutos O processamento ou publicação de documentos falhou em produzir conteúdo utilizável. Retentar após retryAfter.
DynamicRenderingTimeout 520 SystemError Cerca de 5 minutos Renderização dinâmica da página esgotada. Tente novamente após retryAfter, ou tente novamente sem renderDynamicPages.
ProcessingTimeout 520 SystemError Cerca de 5 minutos Processamento de documentos esgotado. Retentar após retryAfter.
PolitenessCancellation 523 SystemError Cerca de 5 minutos O rastreamento foi cancelado para respeitar os limites de rastreamento do anfitrião de origem. O URL não produziu qualquer conteúdo porque o rastreamento não teve sucesso devido à quota limitada de rastreamento do site. Retentar após retryAfter.
HostCrawlTimeout 524 SystemError Cerca de 5 minutos O rastreamento do host de origem expirou. O URL não produziu qualquer conteúdo porque o rastreamento expirou: o host remoto não respondeu a tempo. Retentar após retryAfter.

Quando se aplica um atraso de retentativa, a resposta inclui retryAfter como um carimbo de data ISO 8601 UTC no formato yyyy-MM-ddTHH:mm:ssZ, por "retryAfter": "2026-10-30T01:01:00Z"exemplo . Não tentes novamente antes desse tempo. Quando retryAfter é omitido, não se aplica qualquer orientação de retentativa.

Exemplo de resposta granular ao erro:

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

Erros de navegação de passagem

Estes erros aplicam-se a pedidos de Navegação com contentFormat: "passage", incluindo pedidos de aplicações sem acesso completo a documentos, para os quais "passage" é o formato padrão. Ver Consultar pedidos de passagem.

Condition Código de Erro Estado HTTP userMessage
query em falta, vazio, apenas espaço em branco, ou com mais de 1000 caracteres HandlerInvalidInput 400 Entrada inválida fornecida. Por favor, verifique os parâmetros do seu pedido.
Uma aplicação sem acesso completo a documentos solicita text, html, ou markdown AuthContentFormatForbidden 403 Esta aplicação só tem acesso a passagens. Use contentFormat 'passagem'.

Todos os outros resultados de Browse para pedidos de passagem utilizam os mesmos códigos de estado e códigos de erro que text, html, e markdown pedidos. Isso inclui páginas filtradas, documentos não encontrados, um rastreamento ao vivo pendente (202 Accepted) e falhas de rastreamento.

Erros de Serviço e Infraestrutura

Código de Erro Estado HTTP Category Repetível Description
InternalServerError 500 SystemError Sim (30 e poucos anos) Erro de servidor interno.

Cenários de Erros Comuns

Erros de autenticação (401, 403)

Sintoma: Autenticação falhada ou acesso proibido

Soluções:

  • Verifique se a sua chave API está correta e incluída no x-apikey cabeçalho
  • Verifique se a sua chave API não expirou
  • Assegura-te de que tens as permissões necessárias para o endpoint
  • Contacte o seu representante da Microsoft se os problemas persistirem

Exemplo:

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

Limitação de taxa (429)

Sintoma: Limite de taxa ultrapassado ou quota diária esgotada (AuthUserThrottled ou AuthUserDailyUsageExceeded)

Pedidos acima do limite de taxa do seu AppID devolvem HTTP 429. O seu limite de taxa é mostrado no portal Web IQ.

Soluções:

  • Implementar lógica de repetição com backoff exponencial
  • Aguarde pelo intervalo retryAfter na resposta de erro (por exemplo, "60s") antes de tentar novamente
  • Reduzir a frequência dos pedidos
  • Note que os limites diários de quotas (AuthUserDailyUsageExceeded) são reiniciados diariamente às 00:00 UTC
  • Para solicitar um limite superior, contacte o Suporte Web IQ

Exemplo de Resposta:

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

Parâmetros inválidos (400)

Sintoma: Pedido inadequado devido a parâmetros inválidos

Questões Comuns:

  • Campos obrigatórios em falta (por exemplo, query parâmetro)
  • Valores de parâmetros fora do intervalo (por exemplo, maxResults> 50)
  • Tipos de parâmetros inválidos (por exemplo, cadeia em vez de inteiro)
  • Valores de parâmetros não suportados (por exemplo, inválidos contentFormat)

Soluções:

  • Validar que todos os parâmetros necessários estão presentes
  • Verifique os valores dos parâmetros em relação às restrições documentadas
  • Garantir a formatação JSON correta

Erros de servidor e infraestrutura (500)

Sintoma: Erro inesperado de servidor interno ou serviço a montante (InternalServerError)

Soluções:

  • Verifique o retryAfter campo (por defeito para "30s") e tente novamente o pedido após esperar
  • Implementar repetição com recuo exponencial e aleatoriedade
  • Se o problema persistir, contacte o suporte da Microsoft com o traceId que foi fornecido na resposta

Exemplo de Resposta:

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

Resposta aceite na API Browse (202)

Sintoma: Resposta aceite (202) com url campos e retryAfter no corpo da resposta

Explicação: Quando liveCrawl é "fallback" e o URL não aparece no índice, a API pode iniciar uma rastreabilidade assíncrona e devolver 202 Aceite. O rastreamento ao vivo está sujeito a restrições de cortesia e disponibilidade por parte dos editores; o "plano B" não garante um rastreamento real. O mesmo comportamento aplica-se a todo contentFormat, incluindo passage.

Condução:

  1. Verifique o estado HTTP 202.
  2. Leia retryAfter o corpo da resposta. É um carimbo de data ISO 8601 UTC (por exemplo, "2026-10-30T01:01:00Z") que é o momento mais cedo para tentar novamente.
  3. Espera até essa altura.
  4. Envie o mesmo pedido novamente. O url campo contém a URL a solicitar; por defeito é a URL que solicitou.
  5. Limitar o número de tentativas de sondagem. Um rastreamento que não consegue ser concluído acaba por devolver um erro, como HostCrawlTimeout (524) ou 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

Melhores práticas

  1. Verifica sempre os códigos de estado - Não assumas sucesso
  2. Use traceId para suporte - Inclua traceId ao contactar o suporte
  3. Implementar lógica de retentativa - Usar retrocesso exponencial para erros transitórios
  4. Lidar com 202 respostas - Para a API Browse com crawl ao vivo, espere até à retryAfter hora e tente novamente
  5. Tratar ambos retryAfter os formatos - Usar a duração para AuthUserThrottled, AuthUserDailyUsageExceeded, InternalServerError, e ScopeFailedToApply, e o carimbo temporal ISO 8601 para Browse 202 e erros granulares, incluindo TooManyOnDemandCrawls (429)
  6. Valide antes de enviar - Verifique os parâmetros localmente para evitar erros 400
  7. Use apenas HTTPS - os pedidos HTTP devolvem erros 410