fabric-rest-api-remediate

Name: fabric-rest-api-remediate
Author: PatrickGallucci

16stars1forks

How to install fabric-rest-api-remediate?

patrickgallucci/fabric-skills/fabric-rest-api-remediate

$npx -y skills add PatrickGallucci/fabric-skills --skill fabric-rest-api-remediate

Installs into the current project.

Summary

Diagnose and resolve Microsoft Fabric REST API errors including HTTP 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Throttling, and 5xx server errors. Use when debugging Fabric API authentication failures, Entra ID token issues, insufficient scopes, throttling/rate limiting,

Files · 1

View on GitHub

SKILL.md

1	# Microsoft Fabric REST API remediate
2
3	Structured diagnostic workflows for identifying and resolving errors when calling Microsoft Fabric REST APIs (`https://api.fabric.microsoft.com/v1/`).
4
5	## When to Use This Skill
6
7	- Fabric REST API returns an HTTP error (401, 403, 404, 429, 5xx)
8	- Authentication or token acquisition fails with MSAL
9	- Service principal or managed identity calls are rejected
10	- API calls are being throttled (HTTP 429)
11	- Long running operations (LRO) fail or time out during polling
12	- Pagination with `continuationToken` stops working or returns incomplete results
13	- Capacity API operations fail (create, update, resume, suspend)
14	- Need to implement retry logic with exponential backoff for Fabric APIs
15	- Debugging `errorCode` values in Fabric API error responses
16
17	## Prerequisites
18
19	- Microsoft Entra ID app registration with appropriate Fabric API permissions
20	- PowerShell 7+ with `Az.Accounts` module or MSAL.PS for token acquisition
21	- Access to a Microsoft Fabric workspace (Contributor or higher)
22	- Tenant setting Service principals can use Fabric APIs enabled (if using service principals)
23
24	## Quick Diagnostic: Identify Your Error
25
26	Start here. Match your HTTP status code to the appropriate workflow.
27
28	\| HTTP Status \| Error Category \| Jump To \|
29	\|-------------\|---------------\|---------\|
30	\| 401 \| Authentication / Token \| [Authentication Failures](#workflow-1-authentication-failures-401) \|
31	\| 403 \| Permissions / Authorization \| [Permission Denied](#workflow-2-permission-denied-403) \|
32	\| 404 \| Resource Not Found \| [Resource Not Found](#workflow-3-resource-not-found-404) \|
33	\| 429 \| Throttling / Rate Limit \| [Throttling](#workflow-4-throttling-429) \|
34	\| 430 \| Spark Compute Limit \| [Capacity Limits](#workflow-5-capacity-and-spark-limits-430) \|
35	\| 500/502/503 \| Server Error \| [Server Errors](#workflow-6-server-errors-5xx) \|
36	\| 202 then failure \| LRO Polling Issue \| [LRO remediate](#workflow-7-long-running-operation-failures) \|
37
38	## Understanding Fabric Error Responses
39
40	Every Fabric API error returns an `ErrorResponse` object. Always capture the `requestId` for support escalation.
41
42	```json
43	{
44	"errorCode": "TokenExpired",
45	"message": "The access token has expired.",
46	"moreDetails": [],
47	"relatedResource": {
48	"resourceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
49	"resourceType": "workspace"
50	},
51	"requestId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
52	}
53	```
54
55	Key rules for error handling:
56	1. Parse `errorCode` for programmatic logic (stable, contract-based)
57	2. Never parse `message` programmatically (may change over time)
58	3. Always log `requestId` for support cases
59	4. Check `relatedResource` to identify which resource caused the error
60
61	---
62
63	## Workflow 1: Authentication Failures (401)
64
65	A 401 means the request failed during authentication or access token validation.
66
67	Step 1 — Check the `errorCode` in the response body
68
69	\| errorCode \| Root Cause \| Fix \|
70	\|-----------\|-----------\|-----\|
71	\| `TokenExpired` \| Access token has expired \| Acquire a fresh token and retry \|
72	\| `InsufficientScopes` \| Token missing required scopes \| Request correct scopes in MSAL call \|
73
74	Step 2 — Validate your token
75
76	Run the [diagnostic script](./scripts/Test-FabricApiConnection.ps1) to test connectivity:
77
78	```powershell
79	./scripts/Test-FabricApiConnection.ps1 -TestEndpoint "workspaces"
80	```
81
82	Or decode and inspect your token manually:
83
84	```powershell
85	# Decode JWT token payload (PowerShell)
86	$token = "<your-access-token>"
87	$payload = $token.Split('.')[1]
88	$padding = 4 - ($payload.Length % 4)
89	if ($padding -lt 4) { $payload += '=' * $padding }
90	$decoded = [System.Text.Encoding]::UTF8.GetString(
91	[System.Convert]::FromBase64String($payload)
92	) \| ConvertFrom-Json
93	# Check expiration
94	$expiry = [DateTimeOffset]::FromUnixTimeSeconds($decoded.exp).LocalDateTime
95	Write-Host "Token expires: $expiry"
96	Write-Host "Scopes (scp): $($decoded.scp)"
97	Write-Host "Audience (aud): $($decoded.aud)"
98	```
99
100	Step 3 — Verify scopes match the API
101
102	Fabric REST APIs use scopes in the format `https://api.fabric.microsoft.com/<Scope>`. Common scopes:
103
104	\| Scope \| Purpose \|
105	\|-------\|---------\|
106	\| `Workspace.ReadWrite.All` \| Full workspace CRUD \|
107	\| `Item.ReadWrite.All` \| Full item CRUD \|
108	\| `Item.Read.All` \| Read-only item access \|
109	\| `Item.Execute.All` \| Execute items (notebooks, pipelines) \|
110	\| `<ItemType>.ReadWrite.All` \| Item-specific CRUD (e.g., `Notebook.ReadWrite.All`) \|
111
112	**Step 4 — If using service principal

People who liked this also viewed

6 picks

Type

fabric-rest-api-remediate

16stars1forks

View on GitHub

How to install fabric-rest-api-remediate?

patrickgallucci/fabric-skills/fabric-rest-api-remediate

$npx -y skills add PatrickGallucci/fabric-skills --skill fabric-rest-api-remediate

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Microsoft Fabric REST API remediate
2
3	Structured diagnostic workflows for identifying and resolving errors when calling Microsoft Fabric REST APIs (`https://api.fabric.microsoft.com/v1/`).
4
5	## When to Use This Skill
6
7	- Fabric REST API returns an HTTP error (401, 403, 404, 429, 5xx)
8	- Authentication or token acquisition fails with MSAL
9	- Service principal or managed identity calls are rejected
10	- API calls are being throttled (HTTP 429)
11	- Long running operations (LRO) fail or time out during polling
12	- Pagination with `continuationToken` stops working or returns incomplete results
13	- Capacity API operations fail (create, update, resume, suspend)
14	- Need to implement retry logic with exponential backoff for Fabric APIs
15	- Debugging `errorCode` values in Fabric API error responses
16
17	## Prerequisites
18
19	- Microsoft Entra ID app registration with appropriate Fabric API permissions
20	- PowerShell 7+ with `Az.Accounts` module or MSAL.PS for token acquisition
21	- Access to a Microsoft Fabric workspace (Contributor or higher)
22	- Tenant setting Service principals can use Fabric APIs enabled (if using service principals)
23
24	## Quick Diagnostic: Identify Your Error
25
26	Start here. Match your HTTP status code to the appropriate workflow.
27
28	\| HTTP Status \| Error Category \| Jump To \|
29	\|-------------\|---------------\|---------\|
30	\| 401 \| Authentication / Token \| [Authentication Failures](#workflow-1-authentication-failures-401) \|
31	\| 403 \| Permissions / Authorization \| [Permission Denied](#workflow-2-permission-denied-403) \|
32	\| 404 \| Resource Not Found \| [Resource Not Found](#workflow-3-resource-not-found-404) \|
33	\| 429 \| Throttling / Rate Limit \| [Throttling](#workflow-4-throttling-429) \|
34	\| 430 \| Spark Compute Limit \| [Capacity Limits](#workflow-5-capacity-and-spark-limits-430) \|
35	\| 500/502/503 \| Server Error \| [Server Errors](#workflow-6-server-errors-5xx) \|
36	\| 202 then failure \| LRO Polling Issue \| [LRO remediate](#workflow-7-long-running-operation-failures) \|
37
38	## Understanding Fabric Error Responses
39
40	Every Fabric API error returns an `ErrorResponse` object. Always capture the `requestId` for support escalation.
41
42	```json
43	{
44	"errorCode": "TokenExpired",
45	"message": "The access token has expired.",
46	"moreDetails": [],
47	"relatedResource": {
48	"resourceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
49	"resourceType": "workspace"
50	},
51	"requestId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
52	}
53	```
54
55	Key rules for error handling:
56	1. Parse `errorCode` for programmatic logic (stable, contract-based)
57	2. Never parse `message` programmatically (may change over time)
58	3. Always log `requestId` for support cases
59	4. Check `relatedResource` to identify which resource caused the error
60
61	---
62
63	## Workflow 1: Authentication Failures (401)
64
65	A 401 means the request failed during authentication or access token validation.
66
67	Step 1 — Check the `errorCode` in the response body
68
69	\| errorCode \| Root Cause \| Fix \|
70	\|-----------\|-----------\|-----\|
71	\| `TokenExpired` \| Access token has expired \| Acquire a fresh token and retry \|
72	\| `InsufficientScopes` \| Token missing required scopes \| Request correct scopes in MSAL call \|
73
74	Step 2 — Validate your token
75
76	Run the [diagnostic script](./scripts/Test-FabricApiConnection.ps1) to test connectivity:
77
78	```powershell
79	./scripts/Test-FabricApiConnection.ps1 -TestEndpoint "workspaces"
80	```
81
82	Or decode and inspect your token manually:
83
84	```powershell
85	# Decode JWT token payload (PowerShell)
86	$token = "<your-access-token>"
87	$payload = $token.Split('.')[1]
88	$padding = 4 - ($payload.Length % 4)
89	if ($padding -lt 4) { $payload += '=' * $padding }
90	$decoded = [System.Text.Encoding]::UTF8.GetString(
91	[System.Convert]::FromBase64String($payload)
92	) \| ConvertFrom-Json
93	# Check expiration
94	$expiry = [DateTimeOffset]::FromUnixTimeSeconds($decoded.exp).LocalDateTime
95	Write-Host "Token expires: $expiry"
96	Write-Host "Scopes (scp): $($decoded.scp)"
97	Write-Host "Audience (aud): $($decoded.aud)"
98	```
99
100	Step 3 — Verify scopes match the API
101
102	Fabric REST APIs use scopes in the format `https://api.fabric.microsoft.com/<Scope>`. Common scopes:
103
104	\| Scope \| Purpose \|
105	\|-------\|---------\|
106	\| `Workspace.ReadWrite.All` \| Full workspace CRUD \|
107	\| `Item.ReadWrite.All` \| Full item CRUD \|
108	\| `Item.Read.All` \| Read-only item access \|
109	\| `Item.Execute.All` \| Execute items (notebooks, pipelines) \|
110	\| `<ItemType>.ReadWrite.All` \| Item-specific CRUD (e.g., `Notebook.ReadWrite.All`) \|
111
112	**Step 4 — If using service principal

People who liked this also viewed

6 picks

Type