gestione degli errori di IQ Web Microsoft

Tutte le API v3 restituiscono risposte di errore standardizzate per diagnosticare e risolvere rapidamente i problemi. Questa sezione illustra i codici di stato HTTP, la struttura di risposta agli errori e gli scenari comuni di risoluzione dei problemi.

Note

Tutti i valori di enumerazione stringa non fanno distinzione tra maiuscole e minuscole.

Codici di stato HTTP

Codice di stato	Si applica a	Categoria errore	Description	Cause comuni
200	Tutte le API	Operazione completata	La richiesta è stata accolta.	-
202	Solo Esplora	Accettato	Richiesta accettata per l'elaborazione (ricerca per indicizzazione in tempo reale).	Ricerca per indicizzazione su richiesta in corso quando liveCrawl è "fallback"
400	Tutte le API	Richiesta non valida	Parametri di richiesta non validi.	Campi obbligatori mancanti, valori di parametro non validi, JSON in formato non valido
401	Tutte le API	Unauthorized	Autenticazione non riuscita o mancante.	Chiave API non valida, intestazione x-apikey mancante
403	Tutte le API	Non consentito	Credenziali valide ma autorizzazioni insufficienti.	La chiave API non dispone delle autorizzazioni necessarie
403	Solo Esplora	Non consentito	Contenuto filtrato o ESCLUSO URL.	URL bloccato da criteri o contenuto filtrato
404	Solo Esplora	Non trovato	Documento non trovato.	URL non valido o inaccessibile
410	Tutte le API	Sparito	HTTPS obbligatorio.	Richiesta effettuata tramite HTTP invece di HTTPS
415	Tutte le API	Tipo di supporto non supportato	Tipo di contenuto non supportato.	Intestazione mancante o non corretta content-type
429	Tutte le API	Troppe richieste	Limite di velocità superato. Per Sfoglia con codici di errore granulari, restituiti anche quando vengono richieste troppe ricerche per indicizzazione su richiesta.	Troppe richieste nell'intervallo di tempo o richieste di ricerca per indicizzazione in tempo reale eccessive
430	Solo Esplora	Errore del server	Troppe ricerche per indicizzazione su richiesta (codici di errore legacy).	Richieste di ricerca per indicizzazione in tempo reale eccessive
500	Tutte le API	Errore interno del server	Errore server imprevisto.	Problema temporaneo del server
520	Solo Esplora	Elaborazione del contenuto non riuscita	La pagina è stata recuperata, ma non è possibile produrre contenuto utilizzabile.	Elaborazione dei documenti non riuscita o timeout o timeout del rendering dinamico
523	Solo Esplora	Ricerca per indicizzazione annullata	L'URL non ha prodotto alcun contenuto perché la ricerca per indicizzazione non è riuscita a causa di una quota limitata di ricerca per indicizzazione del sito.	Quota di ricerca per indicizzazione limitata per l'host di origine
524	Solo Esplora	Timeout ricerca per indicizzazione	L'URL non ha prodotto alcun contenuto perché è stato eseguito il timeout della ricerca per indicizzazione.	Timeout dell'host remoto

Gli stati 520, 523 e 524 fanno parte di codici di errore di esplorazione granulari, che sono abilitati per impostazione predefinita.

Struttura della risposta all'errore

Tutte le risposte di errore seguono questo schema:

Field	Type	Description
errorCode	string	Categoria di errore più dettagliata che consente di identificare il tipo di errore.
errorCategory	string	Categoria generale: UserError (lato client/ non riprovabile) o SystemError (lato server/riprovabile).
userMessage	string	Descrizione dell'errore leggibile dall'utente.
technicalDetails	string (facoltativo)	Informazioni tecniche aggiuntive o dettagli di convalida dei parametri per il debug.
retryAfter	string (facoltativo)	Linee guida per i tentativi. Per AuthUserThrottled, AuthUserDailyUsageExceedede InternalServerError, una durata con un "s" suffisso (ad esempio, "60s"). Per Cercare errori granulari, incluso TooManyOnDemandCrawls (429), un timestamp UTC ISO 8601 (ad esempio, "2026-10-30T01:01:00Z") che è la prima volta per riprovare. Omesso quando non si applicano linee guida per i tentativi.
requestId	string (facoltativo)	Identificatore univoco per la richiesta.
traceId	string	ID traccia distribuita per il debug e il supporto Microsoft.

Note

retryAfter usa due formati. AuthUserThrottledLe risposte , AuthUserDailyUsageExceedede InternalServerError usano una durata, "60s"ad esempio . Esplorare le risposte e sfogliare 202 Accepted gli errori granulari usano un timestamp ISO 8601 UTC assoluto, "2026-10-30T01:01:00Z"ad esempio . Lo stato HTTP da solo non determina il formato: TooManyOnDemandCrawls restituisce 429 ma usa un timestamp. La logica di ripetizione dei tentativi deve gestire entrambi i formati.

Note

202 Accepted le risposte (ad esempio, browse live crawl polling) non sono risposte di errore e non usano lo schema di errore precedente. Includono un retryAfter timestamp per indicare quando ripetere la richiesta.

Esempio di risposta di errore:

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

Riferimento ai codici di errore

Errori di convalida della richiesta

Codice di errore	Stato HTTP	Category	Description
RequestInvalidFormat	400	UserError	Corpo JSON in formato non valido o struttura del payload della richiesta non valida.
RequestInvalidMethod	400	UserError	Nome del metodo o dello strumento non valido specificato nella richiesta.
HandlerInvalidInput	400	UserError	Valori dei parametri di input non validi(ad esempio, query vuota, maxResults non compreso nell'intervallo [1, 50], valori di enumerazione non validi. Per sfogliare le richieste di passaggio, query manca, vuoto o più di 1000 caratteri.
RequestBlockedHeader	400	UserError	La richiesta contiene un'intestazione debug/variant bloccata , ad esempio X-Augmentations, X-DebugOptions, X-XapHostOverride. Usare invece parametri URL documentati (?p1=, ?debugoptions=, ?atlahostname=).
RequestUnsupportedMediaType	415	UserError	L'intestazione content-type è mancante o non application/json.
MethodNotAllowed	405	UserError	Metodo HTTP non consentito nella route (ad esempio, GET in un endpoint solo POST).

Errori di autenticazione e autorizzazione

Codice di errore	Stato HTTP	Category	Description
AuthNoToken	401	UserError	Autenticazione richiesta. Nessun token di connessione o chiave API fornita.
AuthTokenParse	401	UserError	Il formato del token di autenticazione o l'analisi dei token non è valida.
AuthInvalidApiKey	401	UserError	La chiave API specificata non è valida o non è riconosciuta.
AuthenticationFailed	401	UserError	Errore di autenticazione generale.
AuthExpiredTrial	401	UserError	Il periodo di valutazione è scaduto. Aggiornare la chiave.
AuthMissingEntryId	400	UserError	Identità dell'applicazione/ID voce mancante nel contesto della richiesta.
AuthAppIdSelectionRequired	400	UserError	L'identità esegue il mapping a più applicazioni. Specificare l'applicazione di destinazione usando il APPID parametro di query. Vedi Chiamata di più appID.
AuthUnauthorizedEntryId	401	UserError	ID voce non autorizzato. Impossibile risolvere l'identità dell'applicazione oppure il parametro di APPID query è stato inviato con l'autenticazione della chiave API.
AuthUnauthorizedAppId	403	UserError	L'oggetto specificato APPID non è associato all'identità.
AuthUnauthorizedService	403	UserError	Il chiamante viene autenticato ma non autorizzato ad accedere al servizio o al verticale richiesto.
AuthBatchEndpointRequired	403	UserError	L'applicazione deve usare l'endpoint batch (X-FD-Batch: 1) per la ricerca Web.
AuthMcpWebForbidden	403	UserError	L'applicazione non è autorizzata a usare lo strumento MCP web .
AuthContentFormatForbidden	403	UserError	Questa applicazione ha accesso solo ai passaggi. Usare contentFormatpassage. Vedi Passaggi e formati di contenuto.

Errori di limitazione della frequenza

Codice di errore	Stato HTTP	Category	Description
AuthUserThrottled	429	UserError	La frequenza delle richieste supera il limite di frequenza di AppID. Controllare retryAfter.
AuthUserDailyUsageExceeded	429	UserError	È stata raggiunta la quota di richiesta giornaliera (reimpostazioni alle 00:00 UTC). Controllare retryAfter.

Esplorare gli errori specifici dell'API

I codici di errore granulari sono abilitati per impostazione predefinita per Sfoglia. Identificano il motivo specifico per cui non è stato possibile restituire una pagina, ad esempio il filtro del contenuto, un documento mancante o un errore di ricerca per indicizzazione e includere indicazioni sui tentativi, se applicabile. Non è richiesta alcuna richiesta di consenso esplicito o di supporto.

I codici granulari e legacy usano la struttura di risposta agli errori standard. Gli errori di esplorazione non elencati qui vengono segnalati come InternalServerError (HTTP 500).

Codici di errore di esplorazione legacy

Questi codici sono stati usati prima che i codici di errore granulari diventassero l'impostazione predefinita. Vengono elencati per riferimento quando si gestiscono le risposte meno recenti.

Codice di errore	Stato HTTP	Category	Description
BrowseApiDocNotFound	404	UserError	Documento non trovato. Nessun contenuto disponibile per l'URL specificato.
BrowseApiIsFilteredOut	403	UserError	Il risultato è stato eliminato dai criteri di contenuto, dal filtro per adulti, dalle restrizioni di accesso o dalle restrizioni di dominio.
BrowseApiIsUrlExcluded	403	UserError	L'URL di destinazione viene escluso da robots.txt o criteri di esclusione della ricerca per indicizzazione.
BrowseApiTooManyOnDemandCrawls	430	UserError	Troppe richieste di ricerca per indicizzazione live su richiesta in corso. Ridurre la frequenza di ricerca per indicizzazione in tempo reale.

Codici di errore di esplorazione granulare

Codice di errore	Stato HTTP	Category	Tipico retryAfter	userMessage	Azione consigliata
InvalidUrl	400	UserError	Mancante	L'URL richiesto non è valido.	Correggere l'URL prima di riprovare.
NotSupported	400	UserError	Mancante	L'URL richiesto non è supportato.	Usare un URL che punta a un documento Web supportato.
URLFilteredOutSpamAdult	403	UserError	Circa 24 ore	L'URL richiesto è stato filtrato in base a criteri di posta indesiderata o per adulti.	Non è possibile restituire la pagina. Non riprovare prima retryAfterdi .
URLFilteredOutEncumbrance	403	UserError	Circa 24 ore	L'URL richiesto è stato filtrato in base alle restrizioni relative al contenuto.	Il criterio dell'editore o del sito, ad esempio direttive robot o regole paywall, non consente la restituzione del contenuto. Non riprovare prima retryAfterdi .
URLFilteredOutSource403Forbidden	403	UserError	Circa 24 ore	L'origine ha negato l'accesso all'URL richiesto.	Il sito di origine ha restituito HTTP 403. Non riprovare prima retryAfterdi .
BrowseApiIsFilteredOut	403	UserError	Circa 24 ore, quando fornito	L'URL richiesto è stato filtrato.	Restituito quando una pagina viene filtrata per un motivo per cui non sono inclusi codici più specifici. Non riprovare prima retryAfterdi .
DocNotFound	404	UserError	Omesso, a meno che non venga fornito dal servizio di ricerca per indicizzazione	Documento richiesto non trovato.	Verificare l'URL o impostare su liveCrawl "fallback" per richiedere una ricerca per indicizzazione dinamica.
TooManyOnDemandCrawls	429	UserError	Quando viene fornito dal servizio di ricerca per indicizzazione	Sono state richieste troppe ricerche per indicizzazione su richiesta.	Ridurre la frequenza di ricerca per indicizzazione in tempo reale. Se retryAfter è presente, attendere fino a quel momento prima di riprovare.
FailedNoContent	520	SystemError	Circa 5 minuti	L'elaborazione o la pubblicazione di documenti non è riuscita a produrre contenuto utilizzabile.	Riprovare dopo retryAfter.
DynamicRenderingTimeout	520	SystemError	Circa 5 minuti	Timeout del rendering di pagina dinamico.	Riprovare dopo retryAftero riprovare senza renderDynamicPages.
ProcessingTimeout	520	SystemError	Circa 5 minuti	Timeout dell'elaborazione dei documenti.	Riprovare dopo retryAfter.
PolitenessCancellation	523	SystemError	Circa 5 minuti	La ricerca per indicizzazione è stata annullata per rispettare i limiti di ricerca per indicizzazione dell'host di origine.	L'URL non ha prodotto alcun contenuto perché la ricerca per indicizzazione non è riuscita a causa di una quota limitata di ricerca per indicizzazione del sito. Riprovare dopo retryAfter.
HostCrawlTimeout	524	SystemError	Circa 5 minuti	Timeout della ricerca per indicizzazione dell'host di origine.	L'URL non ha prodotto alcun contenuto perché è stato eseguito il timeout della ricerca per indicizzazione: l'host remoto non ha risposto in tempo. Riprovare dopo retryAfter.

Quando si applica un ritardo di ripetizione dei tentativi, la risposta include retryAfter come timestamp UTC ISO 8601 nel formato yyyy-MM-ddTHH:mm:ssZ, ad esempio "retryAfter": "2026-10-30T01:01:00Z". Non riprovare prima di quel momento. Quando retryAfter viene omesso, non viene applicato alcun materiale sussidiario per i tentativi.

Esempio di risposta di errore granulare:

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

Esplorare gli errori di passaggio

Questi errori si applicano alle richieste Di esplorazione con contentFormat: "passage", incluse le richieste provenienti dalle applicazioni senza accesso completo al documento, per cui il formato predefinito è "passaggio". Vedere Sfogliare le richieste di passaggio.

Condition	Codice di errore	Stato HTTP	userMessage
query mancante, vuoto, solo spazi vuoti o più lungo di 1000 caratteri	HandlerInvalidInput	400	Input non valido specificato. Controllare i parametri della richiesta.
Un'applicazione senza richieste textdi accesso completo ai documenti , htmlo markdown	AuthContentFormatForbidden	403	Questa applicazione ha accesso solo ai passaggi. Usare contentFormat 'passage'.

Tutti gli altri risultati sfoglia per le richieste di passaggio usano gli stessi codici di stato e codici di errore delle textrichieste , htmle markdown . Inclusi pagine filtrate, documenti non trovati, ricerca per indicizzazione in sospeso (202 Accepted) e errori di ricerca per indicizzazione.

Errori del servizio e dell'infrastruttura

Codice di errore	Stato HTTP	Category	Riprovabile	Description
InternalServerError	500	SystemError	Sì (30 anni)	Errore interno del server.

Scenari di errore comuni

Errori di autenticazione (401, 403)

Sintomo: Autenticazione non riuscita o accesso negato

Soluzioni:

• Verificare che la chiave API sia corretta e inclusa nell'intestazione x-apikey
• Verificare che la chiave API non sia scaduta
• Assicurarsi di disporre delle autorizzazioni necessarie per l'endpoint
• Se i problemi persistono, contattare il rappresentante Microsoft

Esempio:

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

Limitazione della frequenza (429)

Sintomo: Limite di velocità superato o quota giornaliera esaurita (AuthUserThrottled o AuthUserDailyUsageExceeded)

Le richieste al di sopra del limite di velocità di AppID restituiscono HTTP 429. Il limite di velocità viene visualizzato nel portale IQ Web.

Soluzioni:

• Implementare la logica di ripetizione con backoff esponenziale
• Attendere l'intervallo retryAfter nella risposta di errore (ad esempio, "60s") prima di riprovare
• Ridurre la frequenza delle richieste
• Si noti che i limiti di quota giornaliera (AuthUserDailyUsageExceeded) vengono reimpostati ogni giorno alle 00:00 UTC
• Per richiedere un limite superiore, contattare il supporto di IQ Web

Risposta di esempio:

{
  "errorCode": "AuthUserThrottled",
  "errorCategory": "UserError",
  "userMessage": "Rate limit exceeded. Please reduce your request frequency.",
  "retryAfter": "60s",
  "requestId": "req_123",
  "traceId": "trace_456"
}

Parametri non validi (400)

Sintomo: Richiesta non valida a causa di parametri non validi

Problemi comuni:

• Campi obbligatori mancanti (ad esempio, query parametro)
• Valori dei parametri non compresi nell'intervallo (ad esempio, maxResults> 50)
• Tipi di parametro non validi ,ad esempio stringa anziché integer
• Valori dei parametri non supportati (ad esempio, non validi contentFormat)

Soluzioni:

• Verificare che siano presenti tutti i parametri obbligatori
• Controllare i valori dei parametri in base ai vincoli documentati
• Assicurarsi che la formattazione JSON sia corretta

Errori del server e dell'infrastruttura (500)

Sintomo: Errore imprevisto del server interno o del servizio upstream (InternalServerError)

Soluzioni:

• Controllare il retryAfter campo (il valore predefinito è "30s") e ripetere la richiesta dopo l'attesa
• Implementare nuovi tentativi con backoff esponenziale e jitter
• Se il problema persiste, contattare Microsoft supporto tecnico fornito traceId nella risposta

Risposta di esempio:

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

Sfoglia la risposta accettata dall'API (202)

Sintomo: Risposta accettata (202) con url e retryAfter campi nel corpo della risposta

Spiegazione: Quando liveCrawl è "fallback" e l'URL non viene trovato nell'indice, l'API può avviare una ricerca per indicizzazione in modo asincrono e restituire 202 Accettato. La ricerca per indicizzazione in tempo reale è soggetta a restrizioni e disponibilità dell'editore; "fallback" non garantisce una ricerca per indicizzazione effettiva. Lo stesso comportamento si applica a ogni contentFormat, incluso passage.

Manipolazione:

1. Verificare lo stato HTTP 202.
2. Leggere retryAfter dal corpo della risposta. Si tratta di un timestamp UTC ISO 8601 (ad esempio, "2026-10-30T01:01:00Z") che è la prima volta per riprovare.
3. Aspetta fino a quel momento.
4. Inviare di nuovo la stessa richiesta. Il url campo contiene l'URL da richiedere. Il valore predefinito è l'URL richiesto.
5. Limitare il numero di tentativi di polling. Una ricerca per indicizzazione che non può essere completata restituisce un errore, ad esempio HostCrawlTimeout (524) o 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

Procedure consigliate

1. Controllare sempre i codici di stato - Non presupporre l'esito positivo
2. Usare traceId per il supporto - Includere traceId quando si contatta il supporto tecnico
3. Implementare la logica di ripetizione dei tentativi - Usare il backoff esponenziale per gli errori temporanei
4. Gestire le risposte 202 : per l'API Sfoglia con ricerca per indicizzazione in tempo reale, attendere fino al retryAfter momento e riprovare
5. Gestire entrambi i retryAfter formati : usare la durata per AuthUserThrottled, AuthUserDailyUsageExceedede InternalServerErrore il timestamp ISO 8601 per Browse 202 e gli errori granulari, tra cui TooManyOnDemandCrawls (429)
6. Convalida prima dell'invio - Controllare i parametri in locale per evitare 400 errori
7. Usare solo HTTPS : le richieste HTTP restituiranno errori 410