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
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.	Troppe richieste nell'intervallo di tempo
430	Solo Esplora	Errore del server	Troppe ricerche per indicizzazione su richiesta.	Richieste di ricerca per indicizzazione in tempo reale eccessive
500	Tutte le API	Errore interno del server	Errore server imprevisto.	Problema temporaneo del server

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)	Tempo di attesa prima di riprovare.
requestId	string (facoltativo)	Identificatore univoco per la richiesta.
traceId	string	ID traccia distribuita per il debug e il supporto Microsoft.

Note

202 Accepted le risposte (ad esempio, browse live crawl polling) non sono risposte di errore e non usano lo schema di errore precedente. Possono comunque includere un retryAfter valore 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.
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 della risorsa. 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

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 a causa del filtro dei criteri o del contenuto.
BrowseApiIsUrlExcluded	403	UserError	L'URL di destinazione è escluso o non consentito dai criteri.
BrowseApiTooManyOnDemandCrawls	430	UserError	Troppe richieste di ricerca per indicizzazione live su richiesta in corso.

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à della risorsa 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 con retryAfter campo

Spiegazione: Quando liveCrawl è impostato su "fallback" e l'URL deve essere sottoposto a ricerca per indicizzazione, l'API restituisce 202 Accepted con un retryAfter valore che indica quando ripetere la richiesta.

Manipolazione:

# 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

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 e riprovare
5. Convalida prima dell'invio - Controllare i parametri in locale per evitare 400 errori
6. Usare solo HTTPS : le richieste HTTP restituiranno errori 410