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