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.

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
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	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.	Demasiados pedidos numa janela temporal
430	Apenas navegar	Erro do servidor	Demasiados crawls a pedido.	Pedidos excessivos de rastreamento ao vivo
500	Todas as APIs	Erro interno do servidor	Erro inesperado do servidor.	Problema temporário com o servidor

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)	É hora de esperar antes de tentar novamente.
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

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. Ainda assim, podem incluir um retryAfter valor 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).
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 recurso. Verifique retryAfter.
AuthUserDailyUsageExceeded	429	UserError	A quota diária de pedidos foi atingida (reinício às 00:00 UTC). Verifique retryAfter.

Navegar por Erros Específicos da API

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 abandonado devido a políticas ou filtragem de conteúdo.
BrowseApiIsUrlExcluded	403	UserError	O URL alvo é excluído ou proibido pela política.
BrowseApiTooManyOnDemandCrawls	430	UserError	Demasiados pedidos de rastreamento ao vivo em andamento.

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

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 ultrapassado ou quota diária esgotada (AuthUserThrottled ou AuthUserDailyUsageExceeded)

Pedidos acima do limite de taxa do seu recurso retornam 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

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

Explicação: Quando liveCrawl está definido como "fallback" e a URL precisa de ser rastreada, a API devolve 202 Aceite com um retryAfter valor que indica quando tentar novamente o pedido.

Condução:

# 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

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, espera e tenta novamente
5. Valide antes de enviar - Verifique os parâmetros localmente para evitar erros 400
6. Use apenas HTTPS - os pedidos HTTP devolvem erros 410