Feilsøking av Microsoft Fabric REST API-er

Innføring

Denne artikkelen hjelper deg å forstå og feilsøke vanlige feil som returneres av Microsoft Fabric REST API-er. Den forklarer det standard feilformatet som brukes av tjenesten og gir veiledning for å løse de hyppigst forekommende HTTP-statuskodene.

Forstå Microsoft Fabric-feilsvar

Når en feil oppstår under behandling av en forespørsel til Microsoft Fabric REST API, returnerer tjenesten et standardobjekt ErrorResponse i responskroppen.

Når du feilsøker, fang alltid opp og logg , requestIdda det unikt identifiserer forespørselen og er nødvendig når man kontakter Microsoft-support. Forespørsels-ID-en er tilgjengelig både i svarkroppen og i svarhodene.

Viktig!

  • errorCode Verdier er stabile og kontraktbaserte.
  • Den menneskelesbare message teksten kan endre seg over tid og bør ikke analyseres programmessig.

ErrorResponse-skjema

Navn Type Bekrivelse
errorCode string En stabil identifikator for feilbetingelsen. Bruk denne verdien når du implementerer feilhåndteringslogikk.
message string En menneskelesbar beskrivelse av feilen.
moreDetails ErrorResponseDetails[] Valgfri liste over ytterligere feildetaljer.
relatedResource ErrorRelatedResource Informasjon om ressursen knyttet til feilen, hvis aktuelt.
requestId string Den unike identifikatoren til den mislykkede forespørselen. Inkluder denne verdien når du kontakter Microsofts support.

ErrorResponseDetails-skjema

Gir ekstra kontekst for komplekse feilscenarier.

Navn Type Bekrivelse
errorCode string En stabil identifikator som beskriver den spesifikke feildetaljen.
message string En menneskelesbar forklaring av feildetaljen.
relatedResource ErrorRelatedResource Ressursen knyttet til denne spesifikke feildetaljen.

ErrorRelatedResource-skjema

Identifiserer ressursen som er involvert i feilen.

Navn Type Bekrivelse
resourceId string ID-en til ressursen som er involvert i feilen.
resourceType string Typen ressurs (for eksempel arbeidsområde, gjenstand eller kapasitet).

Vanlige HTTP-feilscenarier

De følgende seksjonene beskriver vanlige HTTP-statuskoder returnert av Microsoft Fabric REST API-er, sammen med typiske årsaker og anbefalte løsninger.

API returnerer 401 – Uautorisert

Et 401-svar indikerer at forespørselen mislyktes under autentisering eller validering av tilgangstoken.

Vanlige årsaker

Feilkode Bekrivelse Løsning
TokenExpired Tilgangstokenet har utløpt. Skaff en ny tilgangstoken og prøv forespørselen på nytt.
InsufficientScopes Tilgangstokenet inkluderer ikke de nødvendige scopene. Oppdater applikasjonen for å be om nødvendige omfang som dokumentert i API-spesifikasjonen, eller oppdater Microsoft Entra-applikasjonsregistreringen.

API returnerer 403 – Forbudt

Et 403-svar indikerer at kalleren er autentisert, men ikke har tilstrekkelige tillatelser til å utføre den forespurte operasjonen på målressursen.

Vanlige årsaker

Feilkode Bekrivelse Løsning
InsufficientPrivileges Kalleren har ikke de nødvendige tillatelsene for å få tilgang til ressursen. Be en arbeidsområde- eller ressursadministrator om å gi tilstrekkelige tillatelser til den kallende brukeren eller tjenestelederen.

API returnerer 404 – Ikke funnet

Et 404-svar indikerer at en forespurt eller referert ressurs ikke eksisterer eller ikke er tilgjengelig for den som ringer.

Bemerkning

Individuelle API-er kan definere ytterligere, API-spesifikke feilkoder. Se alltid API-spesifikasjonen for autoritative detaljer.

Vanlige årsaker

Feilkode Bekrivelse Løsning
WorkspaceNotFound Det angitte arbeidsområdet kunne ikke finnes. Sjekk at riktig arbeidsområde-objekt-ID ble oppgitt.
EntityNotFound Den etterspurte ressursen kunne ikke finnes. Bekreft at riktig ressurs-ID ble oppgitt. Den manglende enheten identifiseres i relatedResource feltet for feilresponsen.

API returnerer 429 – For mange forespørsler

Et svar på 429 indikerer at forespørselen ble strupet. Microsoft Fabric returnerer en 429-statuskode av to ulike grunner, hver identifisert med en forskjellig errorCode i responsteksten.

Vanlige årsaker

Feilkode Bekrivelse Løsning
RequestBlocked Forespørselshastigheten oversteg tjenestens begrensningsgrenser. Vent til varigheten som er spesifisert i Retry-After headeren før du prøver på nytt. Se Håndter ratebegrensning i søknaden din.
CapacityLimitExceeded Compute-enhetene (kapasitetsenhetene) som ble brukt på din kapasitet oversteg grensene for den kjøpte Fabric SKU-en. Prøv forespørselen på nytt senere. Se Håndtakskapasitetsthrottling.

Hastighetsbegrensning (RequestBlocked)

En RequestBlocked feil indikerer at forespørselshastigheten oversteg tjenestens begrensningsgrenser.

  • Throttling håndheves i henhold til innringerens identitet.
  • Hastighetsgrenser vurderes vanligvis over ett-minutts vinduer.

Informasjon om omprøvingstidspunkt

Når hastighetsbegrensning skjer, gis retry-informasjon på to steder:

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

  • Retry-After HTTP-responsheader
    Spesifiserer antall sekunder klienten må vente før man prøver på nytt.

Foretrekker Retry-After alltid headeren når du implementerer retry-logikk.

Håndter hastighetsbegrensning i søknaden din

Søknader bør:

  • Oppdage HTTP 429-svar.
  • Analyser og respekter overskriften Retry-After .
  • Bruk en begrenset retry-policy, som eksponentiell backoff med jitter for høyskala scenarier.
  • Unngå uendelige forsøksløkker.

Reduser sannsynligheten for hastighetsbegrensning

  • Bruk bulk- og batchoperasjoner når det er mulig.
  • Foretrekk liste-API-er fremfor gjentatte enkeltressursforespørsler.
  • Cache fikk ofte tilgang til data, spesielt metadata som endres sjelden.
  • Unngå trafikkutbrudd ved å fordele forespørsler jevnt over tid.

Kapasitetsgrense overskredet (CapacityLimitExceeded)

En CapacityLimitExceeded feil indikerer at beregningen (kapasitetsenhetene) som ble brukt på din kapasitet oversteg grensene for den kjøpte Fabric SKU. I motsetning til rate limiting, skyldes ikke denne throttlingen hvor mange API-kall en spesifikk kaller gjør; den reflekterer den totale datakraften som brukes på tvers av alle arbeidsbelastninger på kapasiteten.

Eksempel på respons:

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

Håndteringskapasitetsthrottling

Fordi denne throttlingen avhenger av den totale beregningen som brukes på din kapasitet i stedet for din individuelle forespørselsrate, Retry-After er ikke headeren anvendelig, og det er lite sannsynlig at et nytt forsøk umiddelbart vil lykkes før kapasitetens beregningsbruk faller tilbake innenfor grensene. Søknader bør:

  • Prøv forespørselen på nytt senere ved å bruke en begrenset retry-policy med eksponentiell backoff.
  • Hvis feilen vedvarer, vurder å skalere opp eller ut Fabric-kapasiteten din.

For mer informasjon om kapasitetsenheter, SKU-er og hvordan Fabric-kapasitet forbrukes, se Plan your capacity size.

Summary

Å bygge pålitelige integrasjoner med Microsoft Fabric REST API-er krever robust feilhåndtering og effektive forespørselsmønstre. Ved å forstå feilresponser, respektere throttling-signaler og optimalisere forespørselsmønstre, kan du bygge robuste applikasjoner.

Relatert innhold

For flere spørsmål eller veiledning fra fellesskapet, se Microsoft Fabric Community

  • Last updated on