Rate limit information returned by the Cloud Controller API

Page last updated:

This topic describes rate limit information that is returned by the Cloud Controller API (CAPI).

Note that the Cloud Controller offers several, distinct rate limiters to serve different purposes. Where multiple rate limiters are enabled, information about each will be shared in its own HTTP response header.

Rate limit responses: General

CAPI includes rate limit information in the HTTP header. Each header includes:

X-RateLimit-Limit: 60
X-RateLimit-Reset: 1372700873
X-RateLimit-Remaining: 56

Use this table to understand the rate limit header.

Requests are counted separately in each Cloud Controller instance and each produces an estimate for the total number of remaining requests. The estimate is based on the fraction remaining on the Cloud Controller instance, rounded down to the nearest 10%, multiplied by the global maximum number of attempts. This might result in inconsistent values for the X-RateLimit-Remaining header when running multiple instances of CAPI, such as some requests still being allowed when the header value is 0.

When requests exceed the maximum rate limit value, CAPI returns a 429 Too Many Requests error code with the body CF-RateLimitExceeded for authenticated requests, or CF-IPBasedRateLimitExceeded for unauthenticated requests.

Rate limit responses: Concurrent requests

Operators can limit the number of concurrent, in-flight requests per user, for each Cloud Controller instance. Requests are counted per authenticated UAA user or, if no user is authenticated, per IP address. The count is incremented when a request starts and decremented when CAPI sends its response, so this limiter caps requests that are in progress at the same time rather than the number of requests made over a time interval.

Note This limit applies per CAPI instance rather than across the whole Cloud Foundry platform. For example, if the limit is 10 and there are 2 instances, a user can have up to 20 concurrent requests in progress. For a limiter scoped to service broker operations, see Rate limit responses: Service Brokers.

The limiter supports two modes:

• Blocking: Requests that would exceed the limit are rejected.
• Logging only: Requests are never rejected. Instead, CAPI logs a warning whenever the number of concurrent requests exceeds the limit. This lets operators observe real concurrency before enforcing a blocking limit.

When a request exceeds the blocking limit, CAPI returns 429 Too Many Requests with a Retry-After header suggesting a random retry time between 1 and 5 seconds in the future. The response body is CF-ConcurrentRequestLimitExceeded for authenticated requests, or CF-IPBasedConcurrentRequestLimitExceeded for unauthenticated requests.

Rate limit responses: V2 API

Operators can limit the number of V2 API requests. This includes all v2/* requests except v2/info. Each HTTP header includes the following information:

X-RateLimit-Limit-V2-API: 60
X-RateLimit-Reset-V2-API: 1643767322
X-RateLimit-Remaining-V2-API: 56

The way V2 API requests are counted is the same as for the general rate limiter, and headers contain the same information. See the table for more details. When the maximum rate limit value is exceeded, CAPI returns 429 Too Many Requests with the body CF-RateLimitV2APIExceeded.

Operators can configure CAPI to exempt users and clients with the UAA scope cloud_controller.v2_api_rate_limit_exempt from the V2 API rate limit.

Rate limit responses: Service Brokers

Operators can limit the number of concurrent requests per user, for each Cloud Controller instance, for operations related to service brokers that can be made to CAPI endpoints for the following resource types:

• GET v3/service_instances/:guid/parameters
• GET v3/service_credential_bindings/:guid/parameters
• GET v3/service_route_bindings/:guid/parameters
• PUT|POST|DELETE v2/service_instances
• PUT|POST|DELETE v2/service_bindings
• PUT|POST|DELETE v2/service_keys

Note This limit applies per CAPI instance rather than across the whole Cloud Foundry platform. For example, if the limit is 3 and there are 2 instances, the maximum number of concurrent requests a user can make is 6. For a limiter that caps concurrent requests across all endpoints, see Rate limit responses: Concurrent requests.

A request finishes when CAPI sends a response. This occurs even if that response is 202 Accepted, indicating that an asynchronous operation is to be performed, such as a service broker creating a service instance. For more information, see Asynchronous Operations in the CAPI V3 documentation. This rate limit does not cap the number of asynchronous operations that can be in progress at any one time for any of the above service-related endpoints.

Any requests that breach the concurrency are rate limited, and receive a 429 Too Many Requests response with the body CF-ServiceBrokerRateLimitExceeded (10016) and a Retry-After header. The header gives an absolute time suggesting when the client should attempt to make their request again, typically a random time between 30 and 90 seconds in the future.

Rate limit responses: UAA

The UAA can be configured with rate limits. If UAA runs into the rate limit, the Cloud Controller will return this information transparently to the user. Cloud Controller will return 429 Too Many Requests reponse with the body CF-UaaRateLimited (20008) and a Retry-After header. The client should not retry the request before the time stated in the header passed.

This error can occur in many authenticated endpoints, if not all, and depends on the rate limit configuration in UAA.