specification: API Commons Rate Limits
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/RateLimits
provider: Amazon ECS
providerId: amazon-ecs
created: '2026-05-04'
# Provenance stamped 2026-08-11: this artifact was written by the API Evangelist
# bulk sweep dated 2026-05-04, not harvested from the provider. See roadmap#35.
method: generated
modified: '2026-05-05'
reconciled: true
tags:
  - Rate Limiting
  - Amazon
  - AWS
  - Containers
  - ECS
description: Amazon ECS API requests are throttled per-account, per-Region using AWS's standard token-bucket
  model. Throttle limits are not publicly published per action and can be increased via Service Quotas
  or AWS Support. ThrottlingException / RequestLimitExceeded responses signal throttling. AWS recommends
  exponential backoff with jitter (truncated binary, max 20s) and the standard SDK retry mode.
sources:
  - https://docs.aws.amazon.com/AmazonECS/latest/APIReference/Welcome.html
  - https://docs.aws.amazon.com/general/latest/gr/api-retries.html
  - https://docs.aws.amazon.com/AWSEC2/latest/APIReference/throttling.html
headers:
  requestId: x-amzn-RequestId
  retryAfter: Retry-After
responseCodes:
  throttled: 400
  throttledLegacy: 503
  serviceUnavailable: 503
limits:
  - name: Per-account ECS API throttling
    scope: account/region
    metric: varies
    limit: see Service Quotas console for ECS
    notes: Limits vary per API action (e.g. RunTask, DescribeServices) and per Region. Defaults are not
      publicly listed; use the Service Quotas console or open a support case to view or raise.
  - name: ECS Anywhere registration
    scope: account/region
    metric: varies
    limit: see Service Quotas console for ECS
    notes: Same throttling envelope; subject to ECS Anywhere quota for external instance registrations
      per cluster.
policies:
  - name: Standard retry mode
    description: AWS SDKs default to standard retry mode with truncated binary exponential backoff and
      jitter (b * 2^i, capped at 20s) and a max of 3 attempts unless overridden.
  - name: Adaptive retry mode
    description: Optional client-side rate limiting via token bucket; recommended only when clients are
      pooled per throttle scope (region + resource).
  - name: Quota increases
    description: Most ECS quotas (cluster count, services per cluster, tasks per service, API TPS) can
      be raised via the Service Quotas console or AWS Support.
  - name: ThrottlingException response
    description: AWS returns HTTP 400 with error code ThrottlingException or RequestLimitExceeded; legacy
      services may return 503. Honor Retry-After when present.
maintainers:
  - name: Kin Lane
    email: kin@apievangelist.com
    url: https://apievangelist.com
  - name: Amazon Web Services
    email: support@aws.amazon.com
    url: https://aws.amazon.com