Troubleshoot Microsoft Fabric REST APIs

Introduction

This article helps you understand and troubleshoot common errors returned by Microsoft Fabric REST APIs. It explains the standard error format used by the service and provides guidance for resolving the most frequently encountered HTTP status codes.

Understand Microsoft Fabric Error Responses

When an error occurs while processing a request to the Microsoft Fabric REST API, the service returns a standard ErrorResponse object in the response body.

When troubleshooting, always capture and log the requestId, as it uniquely identifies the request and is required when contacting Microsoft support. The request ID is available both in the response body and in the response headers.

Important

• errorCode values are stable and contract-based.
• The human-readable message text may change over time and should not be parsed programmatically.

ErrorResponse schema

Name	Type	Description
errorCode	string	A stable identifier for the error condition. Use this value when implementing error-handling logic.
message	string	A human-readable description of the error.
moreDetails	ErrorResponseDetails[]	Optional list of additional error details.
relatedResource	ErrorRelatedResource	Information about the resource associated with the error, if applicable.
requestId	string	The unique identifier of the failed request. Include this value when contacting Microsoft support.

ErrorResponseDetails schema

Provides additional context for complex error scenarios.

Name	Type	Description
errorCode	string	A stable identifier describing the specific error detail.
message	string	A human-readable explanation of the error detail.
relatedResource	ErrorRelatedResource	The resource associated with this specific error detail.

ErrorRelatedResource schema

Identifies the resource involved in the error.

Name	Type	Description
resourceId	string	The ID of the resource involved in the error.
resourceType	string	The type of the resource (for example, workspace, item, or capacity).

Common HTTP error scenarios

The following sections describe common HTTP status codes returned by Microsoft Fabric REST APIs, along with typical root causes and recommended resolutions.

API returns 401 – Unauthorized

A 401 response indicates that the request failed during authentication or access token validation.

Common root causes

Error code	Description	Resolution
TokenExpired	The access token has expired.	Acquire a new access token and retry the request.
InsufficientScopes	The access token does not include the required scopes.	Update the application to request the required scopes as documented in the API specification, or update the Microsoft Entra application registration.

API returns 403 – Forbidden

A 403 response indicates that the caller is authenticated but does not have sufficient permissions to perform the requested operation on the target resource.

Common root causes

Error code	Description	Resolution
InsufficientPrivileges	The caller does not have the required permissions to access the resource.	Ask a workspace or resource administrator to grant sufficient permissions to the calling user or service principal.

API returns 404 – Not Found

A 404 response indicates that a requested or referenced resource does not exist or is not accessible to the caller.

Note

Individual APIs may define additional, API-specific error codes. Always refer to the API specification for authoritative details.

Common root causes

Error code	Description	Resolution
WorkspaceNotFound	The specified workspace could not be found.	Verify that the correct workspace object ID was provided.
EntityNotFound	The requested resource could not be found.	Confirm that the correct resource ID was provided. The missing entity is identified in the relatedResource field of the error response.

API returns 429 – Too Many Requests

A 429 response indicates that the request was throttled. Microsoft Fabric returns a 429 status code for two distinct reasons, each identified by a different errorCode in the response body.

Common root causes

Error code	Description	Resolution
RequestBlocked	The request rate exceeded the service's throttling limits.	Wait for the duration specified in the Retry-After header before retrying. See Handle rate limiting in your application.
CapacityLimitExceeded	The compute (capacity units) consumed on your capacity exceeded the limits of the purchased Fabric SKU.	Retry the request later. See Handle capacity throttling.

Rate limiting (RequestBlocked)

A RequestBlocked error indicates that the request rate exceeded the service's throttling limits.

• Throttling is enforced per caller identity.
• Rate limits are typically evaluated over one-minute windows.

Retry timing information

When rate limiting occurs, retry information is provided in two locations:

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

• Retry-After HTTP response header
  Specifies the number of seconds the client must wait before retrying.

Always prefer the Retry-After header when implementing retry logic.

Handle rate limiting in your application

Applications should:

• Detect HTTP 429 responses.
• Parse and honor the Retry-After header.
• Apply a bounded retry policy, such as exponential backoff with jitter for high-scale scenarios.
• Avoid infinite retry loops.

Reduce the likelihood of rate limiting

• Use bulk and batch operations when available.
• Prefer list APIs over repeated single-resource requests.
• Cache frequently accessed data, especially metadata that changes infrequently.
• Avoid traffic bursts by distributing requests evenly over time.

Capacity limit exceeded (CapacityLimitExceeded)

A CapacityLimitExceeded error indicates that the compute (capacity units) consumed on your capacity exceeded the limits of the purchased Fabric SKU. Unlike rate limiting, this throttling isn't caused by the number of API calls a specific caller makes; it reflects the overall compute consumed across all workloads on the capacity.

Example response body:

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

Handle capacity throttling

Because this throttling depends on the overall compute consumed on your capacity rather than your individual request rate, the Retry-After header isn't applicable, and retrying immediately is unlikely to succeed until the capacity's compute usage falls back within its limits. Applications should:

• Retry the request later using a bounded retry policy with exponential backoff.
• If the error persists, consider scaling up or scaling out your Fabric capacity.

For more information about capacity units, SKUs, and how Fabric capacity is consumed, see Plan your capacity size.

Summary

Building reliable integrations with Microsoft Fabric REST APIs requires robust error handling and efficient request patterns. By understanding error responses, honoring throttling signals, and optimizing request patterns, you can build resilient applications.

---

Related content

For additional questions or community guidance, see Microsoft Fabric Community