SAM Doctor

ERROR REFERENCE

API Gateway TooManyRequestsException during deployment

API Gateway rejected a create, deploy, or update request because the account exceeded a control-plane request-rate quota in that Region. This is separate from an API client receiving a runtime HTTP 429.

WHAT IT MEANS

The deployment hit the API Gateway control plane too quickly

The two useful deployment shapes are:

An error occurred (TooManyRequestsException) when calling the CreateDeployment operation: Too Many Requests

CREATE_FAILED AWS::ApiGateway::RestApi Api Too Many Requests (Service: ApiGateway, Status Code: 429)

These messages name an AWS control-plane operation or a failed CloudFormation resource. The 429 is normally transient and does not show that the template is invalid. Immediate, unbounded retries can make the burst worse by adding more requests before the quota recovers.

A bare application response such as GET /orders: 429 Too Many Requests is different. That is runtime traffic and this deployment diagnosis deliberately does not match it.

FIX

Back off first, then remove the source of the burst

  1. Pause before retrying. Retry with exponential backoff and jitter. Do not wrap the deployment in a tight or unlimited loop.
  2. Record the scope. Preserve the operation name, AWS account, and Region from the failed job so you compare deployments sharing the same quota pool.
  3. Serialize API-changing deployments. Reduce CI fan-out that creates or updates API Gateway resources in the same account and Region. A deployment concurrency group is safer than several jobs racing and retrying independently.
  4. Check the actual quota. Open Amazon API Gateway in Service Quotas for the failing Region and compare the named operation with the official control-plane quota table. Request an increase only when that quota is listed as adjustable and the steady request rate is legitimate; otherwise reduce the call rate.
  5. Verify without changing the template. Once request pressure drops, rerun the same deployment and confirm the API Gateway resource reaches CREATE_COMPLETE or UPDATE_COMPLETE without another 429.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor distinguishes API Gateway deployment throttling from bare runtime 429 responses and from generic CloudFormation failures. It runs locally, needs no AWS credentials, and does not upload the log. 

python -m pip install sam-doctor
sam-doctor diagnose deployment.log --format markdown

RELATED