From 0d68f8e3f17d7f0aa2c67071d8020cf104632f49 Mon Sep 17 00:00:00 2001 From: victor-mancera-sp Date: Mon, 4 May 2026 11:35:00 -0600 Subject: [PATCH] APIMGMT-1962: Enhance rate limiting documentation with route-specific backoff details and configuration options. Include YAML example for enabling backoff in API routes across multiple versions. --- docs/api/beta/rate-limit.md | 22 ++++++++++++++++++++++ docs/api/rate-limit.md | 22 ++++++++++++++++++++++ docs/api/v2024/rate-limit.md | 22 ++++++++++++++++++++++ docs/api/v2025/rate-limit.md | 22 ++++++++++++++++++++++ docs/api/v2026/rate-limit.md | 22 ++++++++++++++++++++++ docs/api/v3/rate-limit.md | 22 ++++++++++++++++++++++ 6 files changed, 132 insertions(+) diff --git a/docs/api/beta/rate-limit.md b/docs/api/beta/rate-limit.md index e1b6ab7c8ac2b..65865a801ccad 100644 --- a/docs/api/beta/rate-limit.md +++ b/docs/api/beta/rate-limit.md @@ -25,6 +25,28 @@ separately. If you exceed the rate limit, expect the following response from the - **Retry-After**: [seconds to wait before rate limit resets] +### Route-specific backoff + +Some APIs may apply an additional route-specific backoff when the same client repeatedly exceeds rate limits across multiple intervals. When backoff is active, the API still returns `429 Too Many Requests`, but the `Retry-After` header may be longer than the standard rate-limit reset window. + +Always wait for the full `Retry-After` value before sending another request. If your integration continues to exceed limits, reduce request concurrency or spread requests over a longer period so each `client_id` stays within the documented limits. + +### Route-owner configuration + +Route owners can enable backoff in the API route specification for routes that need escalating retry delays. The authoritative route YAML is maintained in `cloud-api-client-common/api-route-specs/sp-gateway-routes.yaml`. + +```yaml +backOffConfig: + enabled: true + intervalThreshold: 3 # Distinct violated intervals before backoff triggers + tiers: [60, 300, 600, 1200] # Backoff durations per escalation tier, in seconds + violationWindow: 120 # Window for counting violated intervals, in seconds + tierMemoryWindow: 3600 # How long to remember the last tier after expiry, in seconds + redisTimeoutMs: 5 # Max time allowed per Redis backoff operation, in milliseconds +``` + +Backoff is active only when the route has `backOffConfig.enabled: true` and the gateway backoff rollout control is enabled. Omitted or non-positive values fall back to the gateway defaults. + :::info Specific APIs may have different rate limiting. Refer to their specifications for this information. diff --git a/docs/api/rate-limit.md b/docs/api/rate-limit.md index 8d5411b5f3185..e6cc76b70247b 100644 --- a/docs/api/rate-limit.md +++ b/docs/api/rate-limit.md @@ -24,6 +24,28 @@ separately. If you exceed the rate limit, expect the following response from the - **Retry-After**: [seconds to wait before rate limit resets] +### Route-specific backoff + +Some APIs may apply an additional route-specific backoff when the same client repeatedly exceeds rate limits across multiple intervals. When backoff is active, the API still returns `429 Too Many Requests`, but the `Retry-After` header may be longer than the standard rate-limit reset window. + +Always wait for the full `Retry-After` value before sending another request. If your integration continues to exceed limits, reduce request concurrency or spread requests over a longer period so each `client_id` stays within the documented limits. + +### Route-owner configuration + +Route owners can enable backoff in the API route specification for routes that need escalating retry delays. The authoritative route YAML is maintained in `cloud-api-client-common/api-route-specs/sp-gateway-routes.yaml`. + +```yaml +backOffConfig: + enabled: true + intervalThreshold: 3 # Distinct violated intervals before backoff triggers + tiers: [60, 300, 600, 1200] # Backoff durations per escalation tier, in seconds + violationWindow: 120 # Window for counting violated intervals, in seconds + tierMemoryWindow: 3600 # How long to remember the last tier after expiry, in seconds + redisTimeoutMs: 5 # Max time allowed per Redis backoff operation, in milliseconds +``` + +Backoff is active only when the route has `backOffConfig.enabled: true` and the gateway backoff rollout control is enabled. Omitted or non-positive values fall back to the gateway defaults. + :::info Specific APIs may have different rate limiting. Refer to their specifications for this information. diff --git a/docs/api/v2024/rate-limit.md b/docs/api/v2024/rate-limit.md index 3ce16e53be3b4..f94e69f574d02 100644 --- a/docs/api/v2024/rate-limit.md +++ b/docs/api/v2024/rate-limit.md @@ -25,6 +25,28 @@ separately. If you exceed the rate limit, expect the following response from the - **Retry-After**: [seconds to wait before rate limit resets] +### Route-specific backoff + +Some APIs may apply an additional route-specific backoff when the same client repeatedly exceeds rate limits across multiple intervals. When backoff is active, the API still returns `429 Too Many Requests`, but the `Retry-After` header may be longer than the standard rate-limit reset window. + +Always wait for the full `Retry-After` value before sending another request. If your integration continues to exceed limits, reduce request concurrency or spread requests over a longer period so each `client_id` stays within the documented limits. + +### Route-owner configuration + +Route owners can enable backoff in the API route specification for routes that need escalating retry delays. The authoritative route YAML is maintained in `cloud-api-client-common/api-route-specs/sp-gateway-routes.yaml`. + +```yaml +backOffConfig: + enabled: true + intervalThreshold: 3 # Distinct violated intervals before backoff triggers + tiers: [60, 300, 600, 1200] # Backoff durations per escalation tier, in seconds + violationWindow: 120 # Window for counting violated intervals, in seconds + tierMemoryWindow: 3600 # How long to remember the last tier after expiry, in seconds + redisTimeoutMs: 5 # Max time allowed per Redis backoff operation, in milliseconds +``` + +Backoff is active only when the route has `backOffConfig.enabled: true` and the gateway backoff rollout control is enabled. Omitted or non-positive values fall back to the gateway defaults. + :::info Specific APIs may have different rate limiting. Refer to their specifications for this information. diff --git a/docs/api/v2025/rate-limit.md b/docs/api/v2025/rate-limit.md index 7dbb8cff0e770..45af399c7a2d3 100644 --- a/docs/api/v2025/rate-limit.md +++ b/docs/api/v2025/rate-limit.md @@ -25,6 +25,28 @@ separately. If you exceed the rate limit, expect the following response from the - **Retry-After**: [seconds to wait before rate limit resets] +### Route-specific backoff + +Some APIs may apply an additional route-specific backoff when the same client repeatedly exceeds rate limits across multiple intervals. When backoff is active, the API still returns `429 Too Many Requests`, but the `Retry-After` header may be longer than the standard rate-limit reset window. + +Always wait for the full `Retry-After` value before sending another request. If your integration continues to exceed limits, reduce request concurrency or spread requests over a longer period so each `client_id` stays within the documented limits. + +### Route-owner configuration + +Route owners can enable backoff in the API route specification for routes that need escalating retry delays. The authoritative route YAML is maintained in `cloud-api-client-common/api-route-specs/sp-gateway-routes.yaml`. + +```yaml +backOffConfig: + enabled: true + intervalThreshold: 3 # Distinct violated intervals before backoff triggers + tiers: [60, 300, 600, 1200] # Backoff durations per escalation tier, in seconds + violationWindow: 120 # Window for counting violated intervals, in seconds + tierMemoryWindow: 3600 # How long to remember the last tier after expiry, in seconds + redisTimeoutMs: 5 # Max time allowed per Redis backoff operation, in milliseconds +``` + +Backoff is active only when the route has `backOffConfig.enabled: true` and the gateway backoff rollout control is enabled. Omitted or non-positive values fall back to the gateway defaults. + :::info Specific APIs may have different rate limiting. Refer to their specifications for this information. diff --git a/docs/api/v2026/rate-limit.md b/docs/api/v2026/rate-limit.md index 4ac484d189d3d..0a964dc726922 100644 --- a/docs/api/v2026/rate-limit.md +++ b/docs/api/v2026/rate-limit.md @@ -25,6 +25,28 @@ separately. If you exceed the rate limit, expect the following response from the - **Retry-After**: [seconds to wait before rate limit resets] +### Route-specific backoff + +Some APIs may apply an additional route-specific backoff when the same client repeatedly exceeds rate limits across multiple intervals. When backoff is active, the API still returns `429 Too Many Requests`, but the `Retry-After` header may be longer than the standard rate-limit reset window. + +Always wait for the full `Retry-After` value before sending another request. If your integration continues to exceed limits, reduce request concurrency or spread requests over a longer period so each `client_id` stays within the documented limits. + +### Route-owner configuration + +Route owners can enable backoff in the API route specification for routes that need escalating retry delays. The authoritative route YAML is maintained in `cloud-api-client-common/api-route-specs/sp-gateway-routes.yaml`. + +```yaml +backOffConfig: + enabled: true + intervalThreshold: 3 # Distinct violated intervals before backoff triggers + tiers: [60, 300, 600, 1200] # Backoff durations per escalation tier, in seconds + violationWindow: 120 # Window for counting violated intervals, in seconds + tierMemoryWindow: 3600 # How long to remember the last tier after expiry, in seconds + redisTimeoutMs: 5 # Max time allowed per Redis backoff operation, in milliseconds +``` + +Backoff is active only when the route has `backOffConfig.enabled: true` and the gateway backoff rollout control is enabled. Omitted or non-positive values fall back to the gateway defaults. + :::info Specific APIs may have different rate limiting. Refer to their specifications for this information. diff --git a/docs/api/v3/rate-limit.md b/docs/api/v3/rate-limit.md index 9a45934054d39..20b595ef5ae5e 100644 --- a/docs/api/v3/rate-limit.md +++ b/docs/api/v3/rate-limit.md @@ -25,6 +25,28 @@ separately. If you exceed the rate limit, expect the following response from the - **Retry-After**: [seconds to wait before rate limit resets] +### Route-specific backoff + +Some APIs may apply an additional route-specific backoff when the same client repeatedly exceeds rate limits across multiple intervals. When backoff is active, the API still returns `429 Too Many Requests`, but the `Retry-After` header may be longer than the standard rate-limit reset window. + +Always wait for the full `Retry-After` value before sending another request. If your integration continues to exceed limits, reduce request concurrency or spread requests over a longer period so each `client_id` stays within the documented limits. + +### Route-owner configuration + +Route owners can enable backoff in the API route specification for routes that need escalating retry delays. The authoritative route YAML is maintained in `cloud-api-client-common/api-route-specs/sp-gateway-routes.yaml`. + +```yaml +backOffConfig: + enabled: true + intervalThreshold: 3 # Distinct violated intervals before backoff triggers + tiers: [60, 300, 600, 1200] # Backoff durations per escalation tier, in seconds + violationWindow: 120 # Window for counting violated intervals, in seconds + tierMemoryWindow: 3600 # How long to remember the last tier after expiry, in seconds + redisTimeoutMs: 5 # Max time allowed per Redis backoff operation, in milliseconds +``` + +Backoff is active only when the route has `backOffConfig.enabled: true` and the gateway backoff rollout control is enabled. Omitted or non-positive values fall back to the gateway defaults. + :::info Specific APIs may have different rate limiting. Refer to their specifications for this information.