fabric-rest-api-remediate

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.

| HTTP Status | Error Category | Jump To | |-------------|---------------|---------| | 401 | Authentication / Token | [Authentication Failures](#workflow-1-authentication-failures-401) | | 403 | Permissions / Authorization | [Permission Denied](#workflow-2-permission-denied-403) | | 404 | Resource Not Found | [Resource Not Found](#workflow-3-resource-not-found-404) | | 429 | Throttling / Rate Limit | [Throttling](#workflow-4-throttling-429) | | 430 | Spark Compute Limit | [Capacity Limits](#workflow-5-capacity-and-spark-limits-430) | | 500/502/503 | Server Error | [Server Errors](#workflow-6-server-errors-5xx) | | 202 then failure | LRO Polling Issue | [LRO remediate](#workflow-7-long-running-operation-failures) |

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

| errorCode | Root Cause | Fix | |-----------|-----------|-----| | TokenExpired | Access token has expired | Acquire a fresh token and retry | | InsufficientScopes | Token missing required scopes | Request correct scopes in MSAL call |

Step 2 — Validate your token

Run the [diagnostic script](./scripts/Test-FabricApiConnection.ps1) 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:

| Scope | Purpose | |-------|---------| | Workspace.ReadWrite.All | Full workspace CRUD | | Item.ReadWrite.All | Full item CRUD | | Item.Read.All | Read-only item access | | Item.Execute.All | Execute items (notebooks, pipelines) | | <ItemType>.ReadWrite.All | Item-specific CRUD (e.g., Notebook.ReadWrite.All) |

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](./references/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

| errorCode | Root Cause | Fix | |-----------|-----------|-----| | InsufficientPrivileges | Missing workspace/item permissions | Request access from workspace admin |

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

| errorCode | Root Cause | Fix | |-----------|-----------|-----| | WorkspaceNotFound | Invalid workspace ID | Verify the workspace GUID | | EntityNotFound | Invalid resource ID | Check relatedResource in error for details |

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):

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

Step 3 — Reduce throttling likelihood

| Strategy | How | |----------|-----| | Use batch/bulk operations | Prefer List Items over individual Get Item calls | | Cache metadata | Store workspace/item IDs locally, refresh periodically | | Spread requests | Add jitter between calls; avoid burst patterns | | Use pagination efficiently | Follow continuationToken to completion in a single pass |

See [error-codes-reference.md](./references/error-codes-reference.md) for the complete error code table.

Workflow 5: Capacity and Spark Limits (430)

HTTP 430 is Fabric-specific for Spark