Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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-apikeycabeç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
retryAfterna 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,
queryparâ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
retryAftercampo (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
traceIdque 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:
- Verifique o estado HTTP 202.
- Leia
retryAftero 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. - Espera até essa altura.
- Envie o mesmo pedido novamente. O
urlcampo contém a URL a solicitar; por defeito é a URL que solicitou. - 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) 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
Melhores práticas
- Verifica sempre os códigos de estado - Não assumas sucesso
- Use traceId para suporte - Inclua traceId ao contactar o suporte
- Implementar lógica de retentativa - Usar retrocesso exponencial para erros transitórios
-
Lidar com 202 respostas - Para a API Browse com crawl ao vivo, espere até à
retryAfterhora e tente novamente -
Tratar ambos
retryAfteros formatos - Usar a duração paraAuthUserThrottled,AuthUserDailyUsageExceeded,InternalServerError, eScopeFailedToApply, e o carimbo temporal ISO 8601 para Browse 202 e erros granulares, incluindoTooManyOnDemandCrawls(429) - Valide antes de enviar - Verifique os parâmetros localmente para evitar erros 400
- Use apenas HTTPS - os pedidos HTTP devolvem erros 410