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.

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
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	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.	Muitas solicitações na janela de tempo
430	Procurar somente	Erro do servidor	Muitos rastreamentos sob demanda.	Solicitações de rastreamento ao vivo excessivas
500	Todas as APIs	Erro interno do servidor	Erro de servidor inesperado.	Problema temporário do servidor

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)	Hora de aguardar antes de tentar novamente.
`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

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 ainda podem incluir um retryAfter valor 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).
`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 recurso. Verifique `retryAfter`.
`AuthUserDailyUsageExceeded`	429	`UserError`	A cota de solicitação diária foi atingida (redefinições às 00:00 UTC). Verifique `retryAfter`.

Procurar erros específicos da API

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 devido à filtragem de conteúdo ou política.
`BrowseApiIsUrlExcluded`	403	`UserError`	A URL de destino é excluída ou não permitida pela política.
`BrowseApiTooManyOnDemandCrawls`	430	`UserError`	Muitas solicitações de rastreamento ao vivo sob demanda em andamento.

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 recurso 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 com retryAfter campo

Explicação: Quando liveCrawl é definido como "fallback" e a URL precisa ser rastreada, a API retorna 202 Aceito com um retryAfter valor que indica quando repetir a solicitação.

Manuseio:

# 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", "liveCrawl": "fallback"}'

# Response: 202 Accepted with retryAfter
# Wait for the specified time, then retry the same request

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 e tente novamente
Validar antes de enviar – Verificar parâmetros localmente para evitar 400 erros
Usar somente HTTPS – as solicitações HTTP retornarão 410 erros

Comentários

Esta página foi útil?

Última atualização em 2026-10-19

Microsoft tratamento de erros de qi da Web

Códigos de status HTTP

Estrutura de resposta de erro

Referência de códigos de erro

Erros de validação de solicitação

Erros de autenticação e autorização

Erros de limitação de taxa

Procurar erros específicos da API

Erros de serviço e infraestrutura

Cenários de Erro Comuns

Erros de autenticação (401, 403)

Limitação de taxa (429)

Parâmetros inválidos (400)

Erros de servidor e infraestrutura (500)

Procurar resposta aceita da API (202)

Práticas Recomendadas

Comentários

Recursos adicionais