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

[serbrech]

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.

Scenario	HTTP	Error Code	x-ms-failure-cause
Temporary capacity shortage	503	InsufficientCapacity	service
RP throttling	429	Throttled	service
ARM throttling	429	TooManyRequests	gateway
Unexpected RP failure	500	InternalServerError	service

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

[serbrech]

Until this is properly documented and handled by the global ARM monitoring, the only safe way to handle this for RPs is to return a flavor of 400, because 5XX are typically monitored by ARM directly and raise SEV2 on us for errors that we have no control over.