Risolvere i problemi relativi alle API REST di Microsoft Fabric

Introduzione

Questo articolo illustra e risolve gli errori comuni restituiti dalle API REST di Microsoft Fabric. Illustra il formato di errore standard usato dal servizio e fornisce indicazioni per la risoluzione dei codici di stato HTTP rilevati più di frequente.

Informazioni sulle risposte di errore di Microsoft Fabric

Quando si verifica un errore durante l'elaborazione di una richiesta all'API REST di Microsoft Fabric, il servizio restituisce un oggetto standard ErrorResponse nel corpo della risposta.

Durante la risoluzione dei problemi, acquisire e registrare sempre requestId, in quanto identifica in modo univoco la richiesta ed è necessario quando si contatta il supporto tecnico Microsoft. L'ID richiesta è disponibile sia nel corpo della risposta che nelle intestazioni della risposta.

Importante

  • errorCode i valori sono stabili e basati sul contratto.
  • Il testo leggibile message può cambiare nel tempo e non deve essere analizzato a livello di codice.

Schema di risposta di errore

Nome TIPO Description
errorCode string Identificatore stabile per la condizione di errore. Usare questo valore quando si implementa la logica di gestione degli errori.
message string Descrizione leggibile dell'errore.
moreDetails ErrorResponseDetails[] Elenco facoltativo di dettagli aggiuntivi sull'errore.
relatedResource ErrorRelatedResource Informazioni sulla risorsa associata all'errore, se applicabile.
requestId string Identificatore univoco della richiesta non riuscita. Includere questo valore quando si contatta il supporto tecnico Microsoft.

Schema ErrorResponseDetails

Fornisce contesto aggiuntivo per scenari di errore complessi.

Nome TIPO Description
errorCode string Identificatore stabile che descrive i dettagli dell'errore specifici.
message string Spiegazione leggibile dei dettagli dell'errore.
relatedResource ErrorRelatedResource Risorsa associata a questo dettaglio di errore specifico.

Schema ErrorRelatedResource

Identifica la risorsa coinvolta nell'errore.

Nome TIPO Description
resourceId string ID della risorsa coinvolta nell'errore.
resourceType string Tipo della risorsa, ad esempio area di lavoro, elemento o capacità.

Scenari di errore HTTP comuni

Le sezioni seguenti descrivono i codici di stato HTTP comuni restituiti dalle API REST di Microsoft Fabric, insieme alle cause radice tipiche e alle risoluzioni consigliate.

L'API restituisce 401 - Non autorizzato

Una risposta 401 indica che la richiesta non è riuscita durante l'autenticazione o la convalida del token di accesso.

Cause radice comuni

Codice di errore Description Risoluzione
TokenExpired Il token di accesso è scaduto. Acquisire un nuovo token di accesso e ripetere la richiesta.
InsufficientScopes Il token di accesso non include gli scopi richiesti. Aggiornare l'applicazione per richiedere gli ambiti necessari come documentato nella specifica dell'API o aggiornare la registrazione dell'applicazione Microsoft Entra.

L'API restituisce 403 - Accesso negato

Una risposta 403 indica che il chiamante è autenticato ma non dispone di autorizzazioni sufficienti per eseguire l'operazione richiesta sulla risorsa di destinazione.

Cause radice comuni

Codice di errore Description Risoluzione
InsufficientPrivileges Il chiamante non dispone delle autorizzazioni necessarie per accedere alla risorsa. Chiedere a un'area di lavoro o a un amministratore delle risorse di concedere autorizzazioni sufficienti all'utente chiamante o all'entità servizio.

L'API restituisce 404 - Non trovato

Una risposta 404 indica che una risorsa richiesta o a cui si fa riferimento non esiste o non è accessibile al chiamante.

Nota

Le singole API possono definire codici di errore aggiuntivi specifici dell'API. Fare sempre riferimento alla specifica dell'API per informazioni dettagliate autorevoli.

Cause radice comuni

Codice di errore Description Risoluzione
WorkspaceNotFound Impossibile trovare l'area di lavoro specificata. Verificare che sia stato fornito il corretto ID dell'oggetto dell'area di lavoro.
EntityNotFound Impossibile trovare la risorsa richiesta. Verificare che sia stato specificato l'ID risorsa corretto. L'entità mancante viene identificata nel relatedResource campo della risposta di errore.

L'API restituisce 429 - Troppe richieste

Una risposta 429 indica che alla richiesta è stata applicata una limitazione della frequenza. Microsoft Fabric restituisce un codice di stato 429 per due motivi distinti, ognuno identificato da un diverso errorCode nel corpo della risposta.

Cause radice comuni

Codice di errore Description Risoluzione
RequestBlocked La frequenza delle richieste ha superato i limiti di limitazione del servizio. Attendere la durata specificata nell'intestazione Retry-After prima di riprovare. Vedere Gestire la limitazione della frequenza nell'applicazione.
CapacityLimitExceeded Il calcolo (unità di capacità) usato per la capacità ha superato i limiti del Fabric SKU acquistato. Riprova la richiesta più tardi. Consulta Gestione della limitazione della capacità.

Limitazione della frequenza (RequestBlocked)

Un RequestBlocked errore indica che la frequenza delle richieste ha superato i limiti di limitazione del servizio.

  • La limitazione viene applicata per identità del chiamante.
  • I limiti di frequenza vengono in genere valutati in finestre di un minuto.

Informazioni sulla tempistica di ripetizione dei tentativi

Quando si verifica il rate limiting, le informazioni per riprovare vengono fornite in due punti:

  • Corpo della risposta (message)
    Esempio:
    "Request is blocked by the upstream service until: 12/24/2025 17:02:20 (UTC)"

  • Retry-After Intestazione della risposta HTTP
    Specifica il numero di secondi di attesa del client prima di riprovare.

Preferisci sempre l'intestazione Retry-After quando implementi la logica di retry.

Gestire la limitazione della frequenza nell'applicazione

Le applicazioni devono:

  • Rilevare le risposte HTTP 429.
  • Analizzare e rispettare l'intestazione Retry-After.
  • Applicare un criterio di ripetizione dei tentativi delimitato, ad esempio un backoff esponenziale con jitter per scenari su larga scala.
  • Evitare cicli di ripetizione infiniti.

Ridurre la probabilità di limitazione della frequenza

  • Usare operazioni in massa e batch, se disponibili.
  • Preferisce elencare le API rispetto alle richieste ripetute a singola risorsa.
  • Memorizzare nella cache i dati a cui si accede di frequente, in particolare i metadati che cambiano raramente.
  • Evitare picchi di traffico distribuendo le richieste in modo uniforme nel tempo.

Limite di capacità superato (CapacityLimitExceeded)

CapacityLimitExceeded indica che le risorse di calcolo (unità di capacità) consumate dalla capacità hanno superato i limiti dello SKU Fabric acquistato. A differenza della limitazione della velocità, questa limitazione non è causata dal numero di chiamate API effettuate da un chiamante specifico; riflette il calcolo complessivo utilizzato in tutti i carichi di lavoro nella capacità.

Corpo della risposta di esempio:

"Your organization's Fabric compute capacity has exceeded its limits. Try again later."

Gestire la limitazione della capacità

Poiché questa limitazione dipende dalle risorse di calcolo complessivamente consumate dalla capacità anziché dalla frequenza delle singole richieste, l'intestazione Retry-After non è applicabile ed è improbabile che un nuovo tentativo immediato vada a buon fine finché l'utilizzo delle risorse di calcolo della capacità non rientra nei limiti. Le applicazioni devono:

  • Ripetere la richiesta in un secondo momento usando un criterio di ripetizione dei tentativi delimitato con backoff esponenziale.
  • Se l'errore persiste, valutare la possibilità di aumentare verticalmente o orizzontalmente la capacità di Fabric.

Per altre informazioni su unità di capacità, SKU e modalità di utilizzo della capacità Fabric, vedere Pianificare le dimensioni della capacità.

Riassunto

La creazione di integrazioni affidabili con le API REST di Microsoft Fabric richiede una gestione degli errori affidabile e modelli di richiesta efficienti. Comprendendo le risposte di errore, rispettando i segnali di limitazione della frequenza e ottimizzando le modalità di invio delle richieste, è possibile creare applicazioni resilienti.

Contenuti correlati

Per altre domande o indicazioni sulla community, vedere Community di Microsoft Fabric

  • Last updated on