Problemen met MICROSOFT Fabric REST API's oplossen

Introductie

Dit artikel helpt u bij het begrijpen en oplossen van veelvoorkomende fouten die worden geretourneerd door Microsoft Fabric REST API's. Hierin wordt de standaardfoutindeling uitgelegd die door de service wordt gebruikt en biedt richtlijnen voor het oplossen van de meest voorkomende HTTP-statuscodes.

Inzicht krijgen in microsoft Fabric-foutreacties

Wanneer er een fout optreedt tijdens het verwerken van een aanvraag naar de REST API van Microsoft Fabric, retourneert de service een standaardobject ErrorResponse in de hoofdtekst van het antwoord.

Bij het oplossen van problemen moet u de requestIdaanvraag altijd vastleggen en registreren, omdat deze de aanvraag uniek identificeert en vereist is wanneer u contact op neemt met microsoft-ondersteuning. De aanvraag-id is beschikbaar in de hoofdtekst van het antwoord en in de antwoordheaders.

Belangrijk

  • errorCode waarden zijn stabiel en op contracten gebaseerd.
  • De door mensen leesbare message tekst kan na verloop van tijd veranderen en mag niet programmatisch worden geparseerd.

ErrorResponse-schema

Naam Typologie Description
errorCode string Een stabiele identificator voor de foutconditie. Gebruik deze waarde bij het implementeren van logica voor foutafhandeling.
message string Een door mensen leesbare beschrijving van de fout.
moreDetails ErrorResponseDetails[] Optionele lijst met aanvullende foutdetails.
relatedResource ErrorRelatedResource Informatie over de resource die is gekoppeld aan de fout, indien van toepassing.
requestId string De unieke identificatie van het mislukte verzoek. Neem deze waarde op wanneer u contact opneemt met Microsoft Ondersteuning.

ErrorResponseDetails-schema

Biedt aanvullende context voor complexe foutscenario's.

Naam Typologie Description
errorCode string Een stabiele id die de specifieke foutdetails beschrijft.
message string Een leesbare uitleg van de foutdetails.
relatedResource ErrorRelatedResource De resource die gekoppeld is aan dit specifieke foutdetail.

ErrorRelatedResource schema

Identificeert de resource die betrokken is bij de fout.

Naam Typologie Description
resourceId string De ID van de resource die bij de fout hoort.
resourceType string Het type resource (bijvoorbeeld werkruimte, item of capaciteit).

Veelvoorkomende HTTP-foutscenario's

In de volgende secties worden algemene HTTP-statuscodes beschreven die worden geretourneerd door REST API's van Microsoft Fabric, samen met typische hoofdoorzaken en aanbevolen oplossingen.

API retourneert 401 – Niet geautoriseerd

Een 401-antwoord geeft aan dat de aanvraag is mislukt tijdens verificatie- of toegangstokenvalidatie.

Veelvoorkomende oorzaken

Foutcode Description Resolutie / Besluit
TokenExpired Het toegangstoken is verlopen. Een nieuw toegangstoken verkrijgen en de aanvraag opnieuw proberen.
InsufficientScopes Het accesstoken bevat niet de vereiste scopes. Werk de toepassing bij om de vereiste bereiken aan te vragen, zoals beschreven in de API-specificatie, of werk de registratie van de Microsoft Entra-toepassing bij.

API retourneert 403 – Verboden

Een 403-antwoord geeft aan dat de aanroeper is geverifieerd, maar niet over voldoende machtigingen beschikt om de aangevraagde bewerking uit te voeren op de doelresource.

Veelvoorkomende oorzaken

Foutcode Description Resolutie / Besluit
InsufficientPrivileges De aanroeper beschikt niet over de vereiste machtigingen voor toegang tot de resource. Vraag een werkruimte- of resourcebeheerder om voldoende machtigingen toe te wijzen aan de aanroepende gebruiker of service-principal.

API retourneert 404 – Niet gevonden

Een 404-antwoord geeft aan dat een aangevraagde of verwezen resource niet bestaat of niet toegankelijk is voor de aanroeper.

Opmerking

Afzonderlijke API's kunnen aanvullende API-specifieke foutcodes definiëren. Raadpleeg altijd de API-specificatie voor gezaghebbende details.

Veelvoorkomende oorzaken

Foutcode Description Resolutie / Besluit
WorkspaceNotFound Kan de opgegeven werkruimte niet vinden. Controleer of de juiste id van het werkruimteobject is opgegeven.
EntityNotFound Kan de aangevraagde resource niet vinden. Controleer of de juiste resource-id is opgegeven. De ontbrekende entiteit wordt geïdentificeerd in het relatedResource veld van de foutreactie.

API retourneert 429 – Te veel aanvragen

Een 429-antwoord geeft aan dat de aanvraag is beperkt. Microsoft Fabric retourneert een 429-statuscode om twee verschillende redenen, elk geïdentificeerd door een andere errorCode in de antwoordtekst.

Veelvoorkomende oorzaken

Foutcode Description Resolutie / Besluit
RequestBlocked De aanvraagsnelheid heeft de beperkingslimieten van de service overschreden. Wacht tot de duur die is opgegeven in de Retry-After koptekst voordat u het opnieuw probeert. Zie Snelheidsbeperking afhandelen in uw toepassing.
CapacityLimitExceeded De rekenkracht (capaciteitseenheden) die op uw capaciteit worden verbruikt, heeft de limieten overschreden van de aangeschafte Fabric SKU. Probeer de aanvraag later opnieuw. Zie Omgaan met capaciteitsbeperking.

Snelheidsbeperking (RequestBlocked)

Een RequestBlocked fout geeft aan dat de aanvraagsnelheid de beperkingslimieten van de service heeft overschreden.

  • Beperking wordt afgedwongen per afzenderidentiteit.
  • Frequentielimieten worden doorgaans geëvalueerd in vensters van één minuut.

Tijdinformatie voor opnieuw proberen

Wanneer snelheidsbeperking optreedt, vindt u informatie over nieuwe pogingen op twee locaties:

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

  • Retry-After HTTP-antwoordheader
    Hiermee geeft u het aantal seconden op dat de client moet wachten voordat u het opnieuw probeert.

Geef altijd de voorkeur aan de Retry-After header bij het implementeren van herhaal logica.

Snelheidsbeperking in uw toepassing verwerken

Toepassingen moeten:

  • HTTP 429-antwoorden detecteren.
  • Parseren en eren de Retry-After koptekst.
  • Pas een beleid voor opnieuw proberen toe, zoals exponentieel uitstel met jitter voor grootschalige scenario's.
  • Vermijd oneindige herhalingslussen.

De kans op snelheidsbeperking verminderen

  • Gebruik bulk- en batchbewerkingen wanneer deze beschikbaar zijn.
  • Geef de voorkeur aan lijst-API's voor herhaalde aanvragen met één resource.
  • Sla regelmatig gebruikte gegevens in de cache op, met name metagegevens die zelden worden gewijzigd.
  • Vermijd pieken in het verkeer door aanvragen gelijkmatig over de tijd te distribueren.

Capaciteitslimiet overschreden (CapacityLimitExceeded)

Een CapacityLimitExceeded fout geeft aan dat de rekenkracht (capaciteitseenheden) die voor uw capaciteit is verbruikt, de limieten van de aangeschafte Fabric-SKU heeft overschreden. In tegenstelling tot snelheidsbeperking wordt deze beperking niet veroorzaakt door het aantal API-aanroepen dat een specifieke aanroeper doet; het weerspiegelt de totale verbruikte rekenkracht voor alle workloads op de capaciteit.

Voorbeeld van antwoordtekst:

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

Omgaan met capaciteitsbeperking

Omdat deze beperking afhangt van het totale rekenverbruik van uw capaciteit in plaats van van uw individuele aanvraagfrequentie, is de header Retry-After niet van toepassing en is het onwaarschijnlijk dat het opnieuw proberen onmiddellijk succes heeft totdat het rekenverbruik van de capaciteit weer binnen de limieten valt. Toepassingen moeten:

  • Probeer het verzoek later opnieuw met een begrensd retrybeleid met exponentiële wachttijd.
  • Als de fout zich blijft voordoen, kunt u overwegen om uw Fabric capaciteit omhoog of uit te schalen.

Zie Capaciteitsgrootte plannen voor meer informatie over capaciteitseenheden, SKU's en hoe Fabric capaciteit wordt verbruikt.

Samenvatting

Het bouwen van betrouwbare integraties met Microsoft Fabric REST API's vereist robuuste foutafhandeling en efficiënte aanvraagpatronen. Door inzicht te krijgen in foutreacties, het respecteren van beperkingssignalen en het optimaliseren van aanvraagpatronen, kunt u tolerante toepassingen bouwen.

Verwante inhoud

Zie Microsoft Fabric Community voor aanvullende vragen of richtlijnen voor de community

  • Last updated on