Felsöka REST-API:er för Microsoft Fabric

Introduction

Den här artikeln hjälper dig att förstå och felsöka vanliga fel som returneras av Microsoft Fabric REST API:er. Den förklarar standardfelformatet som används av tjänsten och ger vägledning för att lösa de http-statuskoder som oftast påträffas.

Förstå Microsoft Fabric-felsvar

När ett fel inträffar när en begäran bearbetas till Microsoft Fabric REST API returnerar tjänsten ett standardobjekt ErrorResponse i svarstexten.

När du felsöker ska du alltid logga och registrera requestId, eftersom det unikt identifierar begäran och är nödvändigt när du kontaktar Microsofts supportteam. Begärande-ID:t är tillgängligt både i svarstexten och i svarshuvudena.

Viktigt

  • errorCode värden är stabila och kontraktsbaserade.
  • Texten som kan message läsas av människor kan ändras över tid och bör inte parsas programmatiskt.

ErrorResponse-schema

Namn Typ Description
errorCode string En stabil identifierare för feltillståndet. Använd det här värdet när du implementerar felhanteringslogik.
message string En läsbar beskrivning av felet.
moreDetails ErrorResponseDetails[] Valfri lista med ytterligare felinformation.
relatedResource ErrorRelatedResource Information om resursen som är associerad med felet, om tillämpligt.
requestId string Den unika identifieraren för den misslyckade begäran. Inkludera det här värdet när du kontaktar Microsofts support.

ErrorResponseDetails-schema

Ger ytterligare kontext för komplexa felscenarier.

Namn Typ Description
errorCode string En stabil identifierare som beskriver den specifika felinformationen.
message string En begriplig förklaring av feldetaljer.
relatedResource ErrorRelatedResource Resursen som är associerad med den här specifika felinformationen.

Felrelateradresurs-schema

Identifierar resursen som är inblandad i felet.

Namn Typ Description
resourceId string ID:t för resursen som är inblandad i felet.
resourceType string Resurstypen (till exempel arbetsyta, objekt eller kapacitet).

Vanliga HTTP-felscenarier

I följande avsnitt beskrivs vanliga HTTP-statuskoder som returneras av Microsoft Fabric REST-API:er, tillsammans med vanliga rotorsaker och rekommenderade lösningar.

API ger 401 – Obehörig

Ett 401-svar anger att begäran misslyckades under verifieringen av autentiserings- eller åtkomsttoken.

Vanliga grundorsaker

Felkod Description Lösning / Beslut
TokenExpired Åtkomsttoken har upphört att gälla. Hämta en ny åtkomsttoken och försök igen.
InsufficientScopes Åtkomsttokenen innehåller inte de nödvändiga omfången. Uppdatera programmet för att begära de nödvändiga omfången enligt beskrivningen i API-specifikationen eller uppdatera Microsoft Entra programregistrering.

API returnerar 403 – Förbjudet

Ett 403-svar anger att anroparen är autentiserad men inte har tillräcklig behörighet för att utföra den begärda åtgärden på målresursen.

Vanliga grundorsaker

Felkod Description Lösning / Beslut
InsufficientPrivileges Anroparen har inte de behörigheter som krävs för att komma åt resursen. Be en arbetsplats- eller resursadministratör att bevilja tillräcklig behörighet till den anropande användaren eller tjänsthuvudnamnet.

API returnerar 404 – hittades inte

Ett 404-svar anger att en begärd eller refererad resurs inte finns eller inte är tillgänglig för anroparen.

Anmärkning

Enskilda API:er kan definiera ytterligare API-specifika felkoder. Se alltid API-specifikationen för auktoritativ information.

Vanliga grundorsaker

Felkod Description Lösning / Beslut
WorkspaceNotFound Det gick inte att hitta den angivna arbetsytan. Kontrollera att rätt arbetsyteobjekt-ID har angetts.
EntityNotFound Det gick inte att hitta den begärda resursen. Bekräfta att rätt resurs-ID har angetts. Den saknade entiteten identifieras i relatedResource fältet för felsvaret.

API returnerar 429 – för många begäranden

Ett 429-svar innebär att begäran har hastighetsbegränsats. Microsoft Fabric returnerar en 429-statuskod av två olika skäl, som var och en identifieras av en annan errorCode i svarstexten.

Vanliga grundorsaker

Felkod Description Lösning / Beslut
RequestBlocked Begärandefrekvensen överskred tjänstens begränsningsgränser. Vänta tills du har angett varaktigheten Retry-After i rubriken innan du försöker igen. Se Hantera hastighetsbegränsning i ditt program.
CapacityLimitExceeded Beräkningskapaciteten (kapacitetsenheter) som har förbrukats i din kapacitet överskred begränsningarna för den inköpta Fabric-SKU:n. Försök igen senare. Se Hantera kapacitetsbegränsning.

Hastighetsbegränsning (RequestBlocked)

Ett RequestBlocked fel anger att begärandefrekvensen överskred tjänstens begränsningsgränser.

  • Begränsning tillämpas per anroparidentitet.
  • Hastighetsbegränsningar utvärderas vanligtvis under en minuts fönster.

Tidsinformation för återförsök

När hastighetsbegränsning inträffar tillhandahålls återförsöksinformation på två platser:

  • Svarstext (message)
    Exempel:
    "Request is blocked by the upstream service until: 12/24/2025 17:02:20 (UTC)"

  • Retry-After HTTP-svarshuvud
    Anger hur många sekunder klienten måste vänta innan den försöker igen.

Föredra alltid Retry-After headern när du implementerar logik för återförsök.

Hantera hastighetsbegränsning i ditt program

Ansökningar bör:

  • Identifiera HTTP 429-svar.
  • Parsa och respektera Retry-After rubriken.
  • Tillämpa en begränsad återförsöksprincip, till exempel exponentiell backoff med jitter för storskaliga scenarier.
  • Undvik oändliga återförsöksloopar.

Minska sannolikheten för hastighetsbegränsning

  • Använd mass- och batchåtgärder när det är tillgängligt.
  • Föredrar list-API:er framför upprepade begäranden med en enskild resurs.
  • Cachelagrade data som används ofta, särskilt metadata som ändras sällan.
  • Undvik trafiktoppar genom att distribuera begäranden jämnt över tid.

Kapacitetsgränsen har överskridits (CapacityLimitExceeded)

Ett CapacityLimitExceeded-fel indikerar att den beräkningskapacitet (kapacitetsenheter) som förbrukats i din kapacitet överskred gränserna för den Fabric SKU som du har köpt. Till skillnad från frekvensbegränsning orsakas den här strypningen inte av antalet API-anrop som en specifik anropare gör; den återspeglar den totala beräkningskapacitet som förbrukas av alla arbetsbelastningar i kapaciteten.

Exempel på svarstext:

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

Hantera kapacitetsstrypning

Eftersom den här begränsningen beror på den totala beräkningskapacitet som används på din kapacitet, snarare än på din individuella begärandefrekvens, är huvudet Retry-After inte tillämpligt, och att försöka igen direkt kommer sannolikt inte att lyckas förrän kapacitetens beräkningsanvändning har sjunkit tillbaka till en nivå inom gränserna. Ansökningar bör:

  • Gör om begäran senare med en policy för begränsade omförsök och exponentiellt ökande väntetid.
  • Om felet kvarstår bör du överväga att skala upp eller skala ut din Fabric kapacitet.

Mer information om kapacitetsenheter, SKU:er och hur Fabric-kapacitet används finns i Planera kapacitetsstorleken.

Sammanfattning

Att skapa tillförlitliga integreringar med Microsoft Fabric REST API:er kräver robust felhantering och effektiva begärandemönster. Genom att förstå felsvar, uppfylla begränsningssignaler och optimera begärandemönster kan du skapa motståndskraftiga program.

Relaterat innehåll

Ytterligare frågor eller community-vägledning finns i Microsoft Fabric Community

  • Last updated on