Imported from PatrickGallucci/fabric-skills (skills/fabric-rest-api-remediate/SKILL.md). Install upstream with npx skills add PatrickGallucci/fabric-skills --skill fabric-rest-api-remediate. Copyright stays with the author (Complete terms in LICENSE.txt).

Microsoft Fabric REST API remediate

Structured diagnostic workflows for identifying and resolving errors when calling Microsoft Fabric REST APIs (https://api.fabric.microsoft.com/v1/).

When to Use This Skill

• Fabric REST API returns an HTTP error (401, 403, 404, 429, 5xx)
• Authentication or token acquisition fails with MSAL
• Service principal or managed identity calls are rejected
• API calls are being throttled (HTTP 429)
• Long running operations (LRO) fail or time out during polling
• Pagination with continuationToken stops working or returns incomplete results
• Capacity API operations fail (create, update, resume, suspend)
• Need to implement retry logic with exponential backoff for Fabric APIs
• Debugging errorCode values in Fabric API error responses

Prerequisites

• Microsoft Entra ID app registration with appropriate Fabric API permissions
• PowerShell 7+ with Az.Accounts module or MSAL.PS for token acquisition
• Access to a Microsoft Fabric workspace (Contributor or higher)
• Tenant setting Service principals can use Fabric APIs enabled (if using service principals)

Quick Diagnostic: Identify Your Error

Start here. Match your HTTP status code to the appropriate workflow.

Understanding Fabric Error Responses

Every Fabric API error returns an ErrorResponse object. Always capture the requestId for support escalation.

{
  "errorCode": "TokenExpired",
  "message": "The access token has expired.",
  "moreDetails": [],
  "relatedResource": {
    "resourceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "resourceType": "workspace"
  },
  "requestId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
}

Key rules for error handling:

1. Parse errorCode for programmatic logic (stable, contract-based)
2. Never parse message programmatically (may change over time)
3. Always log requestId for support cases
4. Check relatedResource to identify which resource caused the error

Workflow 1: Authentication Failures (401)

A 401 means the request failed during authentication or access token validation.

Step 1 — Check the errorCode in the response body

Step 2 — Validate your token

Run the diagnostic script to test connectivity:

./scripts/Test-FabricApiConnection.ps1 -TestEndpoint "workspaces"

Or decode and inspect your token manually:

# Decode JWT token payload (PowerShell)
$token = "<your-access-token>"
$payload = $token.Split('.')[1]
$padding = 4 - ($payload.Length % 4)
if ($padding -lt 4) { $payload += '=' * $padding }
$decoded = [System.Text.Encoding]::UTF8.GetString(
    [System.Convert]::FromBase64String($payload)
) | ConvertFrom-Json
# Check expiration
$expiry = [DateTimeOffset]::FromUnixTimeSeconds($decoded.exp).LocalDateTime
Write-Host "Token expires: $expiry"
Write-Host "Scopes (scp): $($decoded.scp)"
Write-Host "Audience (aud): $($decoded.aud)"

Step 3 — Verify scopes match the API

Fabric REST APIs use scopes in the format https://api.fabric.microsoft.com/<Scope>. Common scopes:

Step 4 — If using service principal or managed identity

Confirm the Service principals can use Fabric APIs tenant setting is enabled. Not all APIs support service principals — check the individual API reference page for identity support.

See authentication-guide.md for detailed token acquisition examples in PowerShell and C#.

Workflow 2: Permission Denied (403)

A 403 means the caller is authenticated but lacks permissions on the target resource.

Step 1 — Check the errorCode

Step 2 — Verify workspace role

The calling identity needs at least Contributor role for write operations and Viewer for read operations.

Step 3 — Check for API-specific requirements

Some APIs require Fabric Admin permissions. Admin APIs are under /v1/admin/ paths. Confirm the calling identity has the Fabric Administrator role if targeting admin endpoints.

Step 4 — Service principal considerations

If the API call relies on downstream items that don't support service principals, the call fails even if the top-level API does. For example, calling Items - Create Item to create a data warehouse will fail because data warehouses don't support service principal identity.

Workflow 3: Resource Not Found (404)

A 404 means the specified resource doesn't exist or isn't accessible to the caller.

Step 1 — Check the errorCode

Step 2 — Validate your IDs

# List all accessible workspaces to find correct ID
$headers = @{ Authorization = "Bearer $token" }
$response = Invoke-RestMethod -Uri "https://api.fabric.microsoft.com/v1/workspaces" `
    -Headers $headers
$response.value | Select-Object id, displayName | Format-Table

Step 3 — Check URL construction

Fabric API base: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items

Common mistakes: mixing up workspaceId with itemId, using display names instead of GUIDs, or targeting the wrong API version.

Workflow 4: Throttling (429)

A 429 means rate limits have been exceeded. Fabric throttles per caller identity per API within one-minute windows.

Step 1 — Read the Retry-After header

The response includes a Retry-After header indicating seconds to wait. Always use this value rather than hardcoded delays.

Step 2 — Implement bounded retry with exponential backoff

Use the retry helper script:

./scripts/Invoke-FabricApiWithRetry.ps1 `
    -Uri "https://api.fabric.microsoft.com/v1/workspaces" `
    -Token $token `
    -MaxRetries 5

Step 3 — Reduce throttling likelihood

See error-codes-reference.md for the complete error code table.

Workflow 5: Capacity and Spark Limits (430)

HTTP 430 is Fabric-specific for Spark compute limits.

Error message: [TooManyRequestsForCapacity] This spark job can't be run because you have hit a spark compute or API rate limit.

Resolution options:

1. Cancel an active Spark job via the Monitoring Hub
2. Upgrade to a larger capacity SKU (queue limits scale with SKU size)
3. Wait and retry later

Workflow 6: Server Errors (5xx)

Step 1 — Capture the requestId from the response body or header. This is essential for Microsoft Support escalation.

Step 2 — Retry with backoff. Transient 500/502/503 errors often resolve on retry.

Step 3 — Check Fabric service health at Microsoft 365 Service Health or Azure Status.

Step 4 — If persistent, open a support ticket including the requestId, timestamp, and full request/response details.

Workflow 7: Long Running Operation Failures

Fabric uses LRO (Long Running Operations) for time-consuming tasks. An LRO returns HTTP 202 with polling headers.

Step 1 — Capture response headers after 202

Step 2 — Poll the operation status

Two approaches:

1. Use the Location header URL directly (preferred)
2. Construct: GET https://api.fabric.microsoft.com/v1/operations/{operationId}

Step 3 — Handle terminal states

Step 4 — Get the result

If the operation has a result, append /result to the operation URL: GET https://api.fabric.microsoft.com/v1/operations/{operationId}/result

See long-running-operations.md for complete polling implementation patterns.

Workflow 8: Pagination Issues

Fabric uses continuationToken / continuationUri for paginated responses.

Step 1 — Follow the token to completion

$allItems = @()
$uri = "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items"
do {
    $response = Invoke-RestMethod -Uri $uri -Headers $headers
    $allItems += $response.value
    $uri = $response.continuationUri
} while ($uri)

Step 2 — Common pitfalls

remediate Decision Tree

API call fails
├── Got HTTP response?
│   ├── 401 → Check token expiry and scopes
│   ├── 403 → Check workspace role and API identity support
│   ├── 404 → Verify workspace/item GUIDs
│   ├── 429 → Honor Retry-After, implement backoff
│   ├── 430 → Spark capacity limit, scale up or wait
│   ├── 5xx → Retry with backoff, check service health
│   └── 202 → LRO started, poll Location header
├── Network error / timeout?
│   ├── Check DNS resolution for api.fabric.microsoft.com
│   ├── Verify no proxy/firewall blocking HTTPS
│   └── Test with: Invoke-RestMethod -Uri "https://api.fabric.microsoft.com/v1/"
└── Token acquisition failed?
    ├── Check Entra app registration exists
    ├── Verify redirect URI matches
    ├── Confirm API permissions granted and admin-consented
    └── See authentication-guide.md

References

• Error Codes Reference — Complete Fabric API error code table
• Authentication Guide — Token acquisition patterns for PowerShell and C#
• Long Running Operations — LRO polling implementation patterns
• Test-FabricApiConnection.ps1 — Diagnostic connectivity test
• Invoke-FabricApiWithRetry.ps1 — Retry logic with exponential backoff
• Fabric-Api-ErrorHandler.template.ps1 — Starter error handling scaffold