Microsoft tratamento de erros de qi da Web

Todas as APIs v3 retornam respostas de erro padronizadas para ajudá-lo a diagnosticar e resolver problemas rapidamente. Esta seção aborda códigos de status HTTP, estrutura de resposta a erros e cenários comuns de solução de problemas.

A API de Gerenciamento de Clientes v1 usa status de recursos autorizados separados e códigos de status de gerenciamento de escopo e corpos de erro.

Note

Todos os valores de enumeração de cadeia de caracteres não diferenciam maiúsculas de minúsculas.

Códigos de status HTTP

Código de Status Aplica-se a Categoria do Erro Description Causas comuns
200 Todas as APIs Êxito O pedido foi bem-sucedido. -
202 Procurar somente Aceitado Solicitação aceita para processamento (rastreamento dinâmico). Rastreamento sob demanda em andamento quando liveCrawl é "fallback"
400 Todas as APIs Solicitação incorreta Parâmetros de solicitação inválidos. Campos necessários ausentes, valores de parâmetro inválidos, JSON malformado
401 Todas as APIs Unauthorized Falha ou falha na autenticação. Chave de API inválida, cabeçalho x-apikey ausente
403 Todas as APIs Proibido Credenciais válidas, mas permissões insuficientes. A chave de API não tem permissões necessárias
403 Procurar somente Proibido Conteúdo filtrado ou URL excluído. URL bloqueada por política ou conteúdo filtrado
404 Todas as APIs Não encontrado Caminho não encontrado. Caminho de ponto de extremidade com erro ortográfico ou sem suporte
404 Procurar somente Não encontrado Documento não encontrado. URL inválida ou inacessível
410 Todas as APIs Sumiu (Gone) HTTPS necessário. Solicitação feita por HTTP em vez de HTTPS
415 Todas as APIs Tipo de mídia sem suporte Não há suporte para o tipo de conteúdo. Cabeçalho ausente ou incorreto content-type
429 Todas as APIs Número Excessivo de Solicitações Limite de taxa excedido. Para Procurar com códigos de erro granulares, também retornado quando muitos rastreamentos sob demanda são solicitados. Muitas solicitações na janela de tempo ou solicitações de rastreamento ao vivo excessivas
430 Procurar somente Erro do servidor Muitos rastreamentos sob demanda (códigos de erro herdados). Solicitações de rastreamento ao vivo excessivas
500 Todas as APIs Erro interno do servidor Erro de servidor inesperado. Problema temporário do servidor
520 Procurar somente Falha no processamento de conteúdo A página foi recuperada, mas nenhum conteúdo utilizável pôde ser produzido. O processamento de documentos falhou ou atingiu o tempo limite ou a renderização dinâmica atingiu o tempo limite
523 Procurar somente Rastreamento Cancelado A URL não produziu nenhum conteúdo porque o rastreamento não foi bem-sucedido devido à cota de rastreamento de site limitada. Cota de rastreamento limitada para o host de origem
524 Procurar somente Tempo limite de rastreamento A URL não produziu nenhum conteúdo porque o rastreamento atingiu o tempo limite. O host remoto atingiu o tempo limite

Os status 520, 523 e 524 fazem parte dos códigos de erro de navegação granulares, que são habilitados por padrão.

Estrutura de resposta de erro

Todas as respostas de erro seguem este esquema:

Field Tipo Description
errorCode cadeia Uma categoria de erro mais detalhada que ajuda a identificar o tipo de erro.
errorCategory cadeia Categoria de alto nível: UserError (do lado do cliente/não retryable) ou SystemError (server-side/retryable).
userMessage cadeia Descrição de erro legível por humanos.
technicalDetails cadeia de caracteres (opcional) Informações técnicas adicionais ou detalhes de validação de parâmetro para depuração.
retryAfter cadeia de caracteres (opcional) Diretrizes de repetição. Por AuthUserThrottled, AuthUserDailyUsageExceeded, InternalServerErrore ScopeFailedToApply, uma duração com um "s" sufixo (por exemplo, "60s"). Para procurar erros granulares, incluindo TooManyOnDemandCrawls (429), um carimbo de data/hora UTC ISO 8601 (por exemplo, "2026-10-30T01:01:00Z") que é o momento mais antigo para tentar novamente. Omitido quando nenhuma orientação de repetição se aplica.
requestId cadeia de caracteres (opcional) Identificador exclusivo para a solicitação.
traceId cadeia ID de rastreamento distribuído para depuração e suporte Microsoft.

Note

retryAfter usa dois formatos. AuthUserThrottled, AuthUserDailyUsageExceedede InternalServerErroras ScopeFailedToApply respostas usam uma duração como "60s". Procurar 202 Accepted respostas e procurar erros granulares usam um carimbo de data/hora UTC ISO 8601 absoluto, como "2026-10-30T01:01:00Z". O status HTTP sozinho não determina o formato: TooManyOnDemandCrawls retorna 429, mas usa um carimbo de data/hora. A lógica de repetição deve lidar com ambos os formatos.

Note

202 Accepted as respostas (por exemplo, procurar sondagem de rastreamento ao vivo) não são respostas de erro e não usam o esquema de erro acima. Eles incluem um retryAfter carimbo de data/hora para indicar quando repetir a solicitação.

Exemplo de resposta de 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 solicitação

Código do erro Status HTTP Category Description
RequestInvalidFormat 400 UserError Corpo JSON malformado ou estrutura de conteúdo de solicitação inválida.
RequestInvalidMethod 400 UserError Nome da ferramenta ou método inválido especificado na solicitação.
HandlerInvalidInput 400 UserError Valores de parâmetro de entrada inválidos (por exemplo, consulta vazia, maxResults fora do intervalo [1, 50], valores de enumeração inválidos). Para solicitações de passagem procurar, query está ausente, em branco ou com mais de 1.000 caracteres.
RequestBlockedHeader 400 UserError A solicitação contém um cabeçalho de depuração/variante bloqueado (por exemplo, , X-Augmentations, X-DebugOptions). X-XapHostOverride Use parâmetros de URL documentados (?p1=, ?debugoptions=, ?atlahostname=) em vez disso.
RequestUnsupportedMediaType 415 UserError O content-type cabeçalho está ausente ou não application/json.
MethodNotAllowed 405 UserError Método HTTP não permitido na rota (por exemplo, GET em um ponto de extremidade somente POST).

Erros de autenticação e autorização

Código do erro Status HTTP Category Description
AuthNoToken 401 UserError Autenticação necessária. Nenhum token de portador ou chave de API fornecida.
AuthTokenParse 401 UserError Falha na análise de token ou no formato de token de autenticação inválido.
AuthInvalidApiKey 401 UserError A chave de API fornecida é inválida ou não é reconhecida.
AuthenticationFailed 401 UserError Falha geral de autenticação.
AuthExpiredTrial 401 UserError O período de avaliação expirou. Atualize sua chave.
AuthMissingEntryId 400 UserError Identidade do aplicativo/ID de entrada ausente no contexto da solicitação.
AuthAppIdSelectionRequired 400 UserError Sua identidade é mapeada para vários aplicativos. Especifique o aplicativo de destino usando o APPID parâmetro de consulta. Consulte Chamar mais de um AppID.
AuthUnauthorizedEntryId 401 UserError ID de entrada não autorizada. Não foi possível resolver a identidade do aplicativo ou o APPID parâmetro de consulta foi enviado com autenticação de chave de API.
AuthUnauthorizedAppId 403 UserError O especificado APPID não está associado à sua identidade.
AuthUnauthorizedService 403 UserError O chamador é autenticado, mas não autorizado a acessar o serviço solicitado/vertical.
AuthBatchEndpointRequired 403 UserError O aplicativo é necessário para usar o ponto de extremidade em lote (X-FD-Batch: 1) para pesquisa na Web.
AuthMcpWebForbidden 403 UserError O aplicativo não tem permissão para usar a ferramenta MCP web .
AuthContentFormatForbidden 403 UserError Esse aplicativo só tem acesso a passagens. Use contentFormatpassage. Consulte Passagens e formatos de conteúdo.

Erros de limitação de taxa

Código do erro Status HTTP Category Description
AuthUserThrottled 429 UserError A frequência de solicitação excede o limite de taxa do AppID. Verifique retryAfter.
AuthUserDailyUsageExceeded 429 UserError A cota de solicitação diária foi atingida (redefinições às 00:00 UTC). Verifique retryAfter.

Erros de escopo nomeado

Quando scopeName for fornecido, failOnMissingScope o padrão trueserá , inclusive quando omitido ou null. Se o serviço relatar que o escopo necessário não pôde ser aplicado, a Pesquisa na Web, a Pesquisa de Notícias e o Auto retornarão o seguinte status HTTP e errorCode na resposta REST pública:

Condition Código de erro Status de HTTP Action
A pesquisa de escopo confirma se o escopo nomeado está ausente. HandlerInvalidInput 400 Verifique o nome, a conta de cobrança do IQ AppID da Web selecionada e se o novo escopo foi propagado.
O escopo não pode ser aplicado por outro motivo, incluindo uma falha de recuperação ou uma causa desconhecida. ScopeFailedToApply 500 Siga as diretrizes de repetição da resposta com retirada limitada; entre em contato com o Suporte se a falha persistir. Não suponha que o nome do escopo seja inválido.

Um escopo recém-criado pode estar ausente da partição ou da réplica que está tratando a solicitação enquanto a propagação está em andamento. Não altere para failOnMissingScope: false apenas ignorar um erro se o aplicativo exigir resultados com escopo: false permite uma pesquisa de todo o índice sem o escopo.

Com false, um aplicativo mal sucedido relatado é retornado como scopeApplied: false na resposta de pesquisa normal. Um aplicativo bem-sucedido relatado é scopeApplied: true; zero documentos correspondentes não são uma falha de escopo-aplicativo. O campo é omitido quando nenhum resultado do aplicativo é relatado. Sem scopeName, failOnMissingScope não tem efeito.

Nem scopeApplied: true garante failOnMissingScope: true que a definição mais recente foi usada. Consulte a verificação e a distribuição do escopo.

Procurar erros específicos da API

Códigos de erro granulares são habilitados por padrão para Procurar. Eles identificam o motivo específico pelo qual uma página não pôde ser retornada, como filtragem de conteúdo, um documento ausente ou uma falha de rastreamento, e incluem diretrizes de repetição quando aplicável. Nenhuma solicitação de aceitação ou suporte é necessária.

Códigos granulares e herdados usam a estrutura de resposta de erro padrão. Os erros de navegação que não estão listados aqui são relatados como InternalServerError (HTTP 500).

Códigos de erro de Procura Herdado

Esses códigos foram usados antes que os códigos de erro granulares se tornassem o padrão. Eles são listados para referência ao lidar com respostas mais antigas.

Código do erro Status HTTP Category Description
BrowseApiDocNotFound 404 UserError Documento não encontrado. Nenhum conteúdo disponível para a URL especificada.
BrowseApiIsFilteredOut 403 UserError O resultado foi descartado pela política de conteúdo, filtragem de adultos, restrições de acesso ou restrições de domínio.
BrowseApiIsUrlExcluded 403 UserError A URL de destino é excluída por robots.txt ou políticas de exclusão de rastreamento.
BrowseApiTooManyOnDemandCrawls 430 UserError Muitas solicitações de rastreamento ao vivo sob demanda em andamento. Reduza a taxa de rastreamento ao vivo.

Códigos de erro de Navegação Granular

Código do erro Status HTTP Category Típico retryAfter userMessage Ação recomendada
InvalidUrl 400 UserError Omitido A URL solicitada é inválida. Corrija a URL antes de tentar novamente.
NotSupported 400 UserError Omitido Não há suporte para a URL solicitada. Use uma URL que aponte para um documento Web com suporte.
URLFilteredOutSpamAdult 403 UserError Cerca de 24 horas A URL solicitada foi filtrada por spam ou política adulta. A página não pode ser retornada. Não tente novamente antes retryAfter.
URLFilteredOutEncumbrance 403 UserError Cerca de 24 horas A URL solicitada foi filtrada por restrições de conteúdo. A política de editor ou site, como diretivas de robôs ou regras de paywall, não permite que o conteúdo seja retornado. Não tente novamente antes retryAfter.
URLFilteredOutSource403Forbidden 403 UserError Cerca de 24 horas A origem negou acesso à URL solicitada. O site de origem retornou HTTP 403. Não tente novamente antes retryAfter.
BrowseApiIsFilteredOut 403 UserError Cerca de 24 horas, quando fornecido A URL solicitada foi filtrada. Retornado quando uma página é filtrada por um motivo que nenhum código mais específico aborda. Não tente novamente antes retryAfter.
DocNotFound 404 UserError Omitido, a menos que fornecido pelo serviço de rastreamento O documento solicitado não foi encontrado. Verifique a URL ou defina liveCrawl como "fallback" para solicitar um rastreamento dinâmico.
TooManyOnDemandCrawls 429 UserError Quando fornecido pelo serviço de rastreamento Muitos rastreamentos sob demanda foram solicitados. Reduza a taxa de rastreamento ao vivo. Se retryAfter estiver presente, aguarde até esse momento antes de tentar novamente.
FailedNoContent 520 SystemError Cerca de 5 minutos Falha no processamento ou publicação de documentos para produzir conteúdo utilizável. Tente novamente depois retryAfter.
DynamicRenderingTimeout 520 SystemError Cerca de 5 minutos A renderização de página dinâmica atingiu o tempo limite. Tente novamente depois retryAfterou tente novamente sem renderDynamicPages.
ProcessingTimeout 520 SystemError Cerca de 5 minutos O processamento de documentos atingiu o tempo limite. Tente novamente depois retryAfter.
PolitenessCancellation 523 SystemError Cerca de 5 minutos O rastreamento foi cancelado para respeitar os limites de rastreamento do host de origem. A URL não produziu nenhum conteúdo porque o rastreamento não foi bem-sucedido devido à cota de rastreamento de site limitada. Tente novamente depois retryAfter.
HostCrawlTimeout 524 SystemError Cerca de 5 minutos O rastreamento do host de origem atingiu o tempo limite. A URL não produziu nenhum conteúdo porque o rastreamento atingiu o tempo limite: o host remoto não respondeu a tempo. Tente novamente depois retryAfter.

Quando um atraso de repetição se aplica, a resposta inclui retryAfter como um carimbo de data/hora UTC ISO 8601 no formato yyyy-MM-ddTHH:mm:ssZ, por exemplo "retryAfter": "2026-10-30T01:01:00Z". Não tente novamente antes dessa hora. Quando retryAfter é omitido, nenhuma orientação de repetição se aplica.

Exemplo de resposta de erro granular:

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

Procurar erros de passagem

Esses erros se aplicam a solicitações procurar com contentFormat: "passage", incluindo solicitações de aplicativos sem acesso completo a documentos, para os quais "passagem" é o formato padrão. Consulte Procurar solicitações de passagem.

Condition Código do erro Status HTTP userMessage
query ausente, vazio, somente espaço em branco ou com mais de 1000 caracteres HandlerInvalidInput 400 Entrada inválida fornecida. Verifique os parâmetros de solicitação.
Um aplicativo sem solicitações completas textde acesso a documentos, htmlou markdown AuthContentFormatForbidden 403 Esse aplicativo só tem acesso a passagens. Use contentFormat 'passage'.

Todos os outros resultados procurar solicitações de passagem usam os mesmos códigos de status e códigos de erro que text, htmle markdown solicitações. 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 do erro Status HTTP Category Com nova tentativa Description
InternalServerError 500 SystemError Sim (30s) Erro interno do servidor.

Cenários de Erro Comuns

Erros de autenticação (401, 403)

Sintoma: Falha na autenticação ou acesso proibido

Soluções:

  • Verifique se a chave de API está correta e incluída no x-apikey cabeçalho
  • Verifique se a chave de API não expirou
  • Verifique se você tem as permissões necessárias para o ponto de extremidade
  • Entre em contato com seu representante do Microsoft se os problemas persistirem

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

Limitação de taxa (429)

Sintoma: Limite de taxa excedido ou cota diária esgotada (AuthUserThrottled ou AuthUserDailyUsageExceeded)

As solicitações acima do limite de taxa do AppID retornam HTTP 429. O limite de taxa é mostrado no portal de Perguntas Frequentes da Web.

Soluções:

  • Implementar lógica de repetição de retirada exponencial
  • Aguarde o retryAfter intervalo na resposta de erro (por exemplo, "60s") antes de tentar novamente
  • Reduzir a frequência de solicitação
  • Observe que os limites de cota diários (AuthUserDailyUsageExceeded) são redefinidos diariamente às 00:00 UTC
  • Para solicitar um limite mais alto, entre em contato com o Suporte a Perguntas Frequentes da Web

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: Solicitação incorreta devido a parâmetros inválidos

Problemas comuns:

  • Campos necessários ausentes (por exemplo, query parâmetro)
  • Valores de parâmetro fora do intervalo (por exemplo, maxResults> 50)
  • Tipos de parâmetro inválidos (por exemplo, cadeia de caracteres em vez de inteiro)
  • Valores de parâmetro sem suporte (por exemplo, inválidos contentFormat)

Soluções:

  • Validar se todos os parâmetros necessários estão presentes
  • Verificar valores de parâmetro em relação a restrições documentadas
  • Garantir a formatação JSON adequada

Erros de servidor e infraestrutura (500)

Sintoma: Erro inesperado do servidor interno ou do serviço upstream (InternalServerError)

Soluções:

  • Verifique o retryAfter campo (o padrão é "30s") e repita a solicitação depois de aguardar
  • Implementar repetição com retirada exponencial e tremulação
  • Se o problema persistir, entre em contato Microsoft suporte com o traceId 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"
}

Procurar resposta aceita da API (202)

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

Explicação: Quando liveCrawl é "fallback" e a URL não é encontrada no índice, a API pode iniciar um rastreamento de forma assíncrona e retornar 202 Aceito. O rastreamento ao vivo está sujeito a restrições de educação e disponibilidade do editor; "fallback" não garante um rastreamento real. O mesmo comportamento se aplica a cada contentFormat, incluindo passage.

Manuseio:

  1. Verifique o status HTTP 202.
  2. Ler retryAfter do corpo da resposta. É um carimbo de data/hora ISO 8601 UTC (por exemplo, "2026-10-30T01:01:00Z") que é o momento mais antigo para tentar novamente.
  3. Aguarde até que o tempo.
  4. Envie a mesma solicitação novamente. O url campo contém a URL a ser solicitada; ele usa como padrão a URL solicitada.
  5. Limite o número de tentativas de sondagem. Um rastreamento que não pode ser concluído eventualmente retorna 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

Práticas Recomendadas

  1. Sempre verificar códigos de status – Não suponha êxito
  2. Usar traceId para suporte – Incluir traceId ao entrar em contato com o suporte
  3. Implementar lógica de repetição – Usar a retirada exponencial para erros transitórios
  4. Manipular respostas 202 – Para procurar a API com rastreamento dinâmico, aguarde até a retryAfter hora e tente novamente
  5. Manipular ambos os retryAfter formatos – Use a duração de AuthUserThrottled, AuthUserDailyUsageExceeded, InternalServerErrore , e ScopeFailedToApplyo carimbo de data/hora ISO 8601 para Procurar 202 e erros granulares, incluindo TooManyOnDemandCrawls (429)
  6. Validar antes de enviar – Verificar parâmetros localmente para evitar 400 erros
  7. Usar somente HTTPS – as solicitações HTTP retornarão 410 erros