Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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-apikeycabeç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
retryAfterintervalo 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,
queryparâ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
retryAftercampo (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
traceIdfornecido 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:
- Verifique o status HTTP 202.
- Ler
retryAfterdo 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. - Aguarde até que o tempo.
- Envie a mesma solicitação novamente. O
urlcampo contém a URL a ser solicitada; ele usa como padrão a URL solicitada. - Limite o número de tentativas de sondagem. Um rastreamento que não pode ser concluído eventualmente retorna um erro, como
HostCrawlTimeout(524) ouFailedNoContent(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
- Sempre verificar códigos de status – Não suponha êxito
- Usar traceId para suporte – Incluir traceId ao entrar em contato com o suporte
- Implementar lógica de repetição – Usar a retirada exponencial para erros transitórios
-
Manipular respostas 202 – Para procurar a API com rastreamento dinâmico, aguarde até a
retryAfterhora e tente novamente -
Manipular ambos os
retryAfterformatos – Use a duração deAuthUserThrottled,AuthUserDailyUsageExceeded,InternalServerErrore , eScopeFailedToApplyo carimbo de data/hora ISO 8601 para Procurar 202 e erros granulares, incluindoTooManyOnDemandCrawls(429) - Validar antes de enviar – Verificar parâmetros localmente para evitar 400 erros
- Usar somente HTTPS – as solicitações HTTP retornarão 410 erros