Resource Provider Guidance Needed for Capacity Exhaustion and Capacity-Constrained Responses

The issue is about adding guidance to the ARM/RP contract. Start by reviewing the existing Microsoft REST API Guidelines, particularly sections on error handling and HTTP status codes. Look for existing documentation on error codes like 'Throttled' or 'InternalServerError' to understand the current structure. 'Done' means the proposed guidance is integrated into the guidelines, with clear examples for the new error codes and the x-ms-failure-cause mapping.

Description

The Azure ecosystem currently lacks clear, Azure-wide guidance for Resource Providers on how to surface capacity-related failures to customers.

Today, similar capacity constraints are exposed inconsistently across Azure using a mix of:

• 400 BadRequest
• 409 Conflict
• 429 TooManyRequests
• 500 InternalServerError
• RP-specific error codes and semantics

This inconsistency makes it difficult for customers, SDKs, ARM tooling, and dependent Azure services to reliably distinguish between:

• Invalid requests that require customer action
• Resource conflicts
• Request throttling
• Temporary service-side capacity shortages
• Unexpected RP failures

Capacity exhaustion is fundamentally different from both a malformed request and an internal implementation error. A valid request may become satisfiable later without modification, yet there is currently no documented ARM / RP guidance defining the expected HTTP status code, error contract, retry semantics, or failure classification.

Proposal

Add explicit guidance to the ARM / RP contract for temporary capacity shortages.

Recommended response:

503 Service Unavailable
Retry-After: <optional>
x-ms-error-code: InsufficientCapacity

{
  "error": {
    "code": "InsufficientCapacity",
    "message": "The service currently has insufficient capacity to fulfill this request."
  }
}

Additionally, define a small set of canonical capacity-related error codes, for example:

• InsufficientCapacity
• RegionalCapacityExceeded
• ZonalCapacityExceeded
• SkuCapacityUnavailable
• PlacementCapacityUnavailable

and document expected retry behavior for each.

x-ms-failure-cause Guidance

Provide explicit guidance for x-ms-failure-cause so capacity shortages can be distinguished from throttling and implementation defects.

This would allow Azure services and customers to handle capacity conditions consistently across Resource Providers while improving diagnostics, automation, and customer experience.