Categories of AWS SDK Failures

Most AWS SDK incidents are not new bugs. They are the same four failure modes wearing a different service's name tag.

Once you can sort a symptom into a bucket, the diagnosis path is nearly automatic. This page gives you that map before the deeper defect walkthroughs later in this section.

Summary

• Four buckets: auth/credential failures, throttling/rate limits, retry logic gone wrong, and data-consistency surprises.
• Insight: the symptom (an exception name) tells you the bucket; the root cause is almost always in how the client or caller was built, not a one-off AWS glitch.
• Key Concepts: ExpiredTokenException, ThrottlingException, retry storms, eventual consistency, ConsistentRead.
• When to Use: the first minute of any AWS SDK incident, to triage before you dig into logs.
• Limitations/Trade-offs: the buckets can compound - a retry storm can look like throttling, and expired credentials can look like an access-denied bug.
• Related Topics: debugging basics, the individual defect walkthroughs, production incident response.

Foundations

Auth and credential failures. These show up as ExpiredTokenException, UnrecognizedClientException, or a sudden AccessDenied on a call that worked a moment ago. The cause is almost never a permissions change. It is far more often a long-lived process holding a snapshot of temporary credentials (from STS or SSO) past their expiry, instead of letting the SDK's credential provider chain refresh them.

Throttling and rate limits. ThrottlingException, TooManyRequestsException, and S3's SlowDown all mean the same thing: you exceeded a rate limit AWS enforces per account, per service, per operation. This is expected behavior under load, not a defect in the service. The defect, if there is one, is in how your client responds to it.

Retry logic gone wrong. Both SDKs retry safely by default. Trouble starts when someone reimplements retries by hand - fixed delay, no jitter, no cap - or disables the built-in strategy. Under a real outage, many clients retrying in lockstep can turn a partial degradation into a full outage.

Data-consistency surprises. A write completes successfully, but the very next read does not reflect it - or a role you just created gets AccessDenied for a few seconds. This bucket is really a set of per-service consistency guarantees that differ from what people assume.

Mechanics & Interactions

These buckets interact more than they first appear to.

A credential that is one minute from expiring can produce an error that looks like throttling if your error handling is too broad and just logs "AWS call failed." A retry storm caused by naive retry logic often manifests as an increase in ThrottlingException counts, because the retries themselves are now the load. And a consistency surprise right after a CreateRole call can look like an auth bug, when the real issue is IAM propagation delay, not a bad policy.

# --- Python (boto3) ---
from botocore.exceptions import ClientError
 
try:
    response = client.some_operation()
except ClientError as err:
    code = err.response["Error"]["Code"]
    # Route by code, not by a generic "it failed" log line.
    if code in ("ExpiredTokenException", "UnrecognizedClientException"):
        print("auth/credential bucket")
    elif code in ("ThrottlingException", "TooManyRequestsException", "SlowDown"):
        print("throttling bucket")
    else:
        print(f"other: {code}")

// --- TypeScript (AWS SDK v3) ---
try {
  await client.send(command);
} catch (err) {
  const name = (err as { name?: string }).name;
  // Route by name, not by a generic catch-all message.
  if (name === "ExpiredTokenException" || name === "UnrecognizedClientException") {
    console.log("auth/credential bucket");
  } else if (name === "ThrottlingException" || name === "SlowDown") {
    console.log("throttling bucket");
  } else {
    console.log(`other: ${name}`);
  }
}

This is the habit worth building: branch on the error code or name first, before you decide which playbook to reach for.

Advanced Considerations & Applications

At scale, the same bucket can present differently depending on where in the stack it is observed.

• Auth failures cluster in time. If ExpiredTokenException appears across many hosts at roughly the same moment, it usually means a fleet of long-running processes all cached credentials near the same startup time. A single host failing intermittently points elsewhere.
• Throttling has a shape. A steady trickle of ThrottlingException under normal load suggests you are near a real service limit and should request a quota increase or batch requests. A sudden spike usually means a traffic pattern change (a backfill job, a new caller) rather than a limit that moved.
• Retry storms are self-inflicted amplifiers. They rarely start an outage; they make an existing partial outage worse by multiplying request volume at the exact moment the dependency is least able to serve it.
• Consistency surprises are mostly documentation gaps. The fix is almost always "read the consistency model for this specific API," since it varies: S3 writes are strongly consistent (since December 2020), DynamoDB reads are eventually consistent by default, and IAM changes propagate globally over a few seconds.

Common Misconceptions

• "Any AWS error is a throttling problem." Only ThrottlingException/SlowDown/TooManyRequestsException are. Auth errors and validation errors need a different fix entirely.
• "S3 is still eventually consistent, so I need to poll after a write." Not since December 2020. S3 now provides strong read-after-write consistency for all requests.
• "Retries always make things better." Naive, unbounded retries without backoff and jitter can turn a brief blip into a cascading failure.
• "If credentials worked an hour ago, they still work now." Temporary credentials from STS or SSO expire; a cached snapshot in a long-lived process will eventually go stale.
• "IAM changes take effect instantly." A new role or policy can take a few seconds to propagate globally before every region honors it.

FAQs

Related

• Debugging Basics - reading the error and finding the root cause fast.
• Throttling & Rate-Limit Defect Walkthrough - the throttling bucket in depth.
• Credential Expiry & Silent Auth Failures - the auth bucket in depth.
• Production Incident Response for AWS-Backed Services - the playbook once you have a bucket.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+). 3730363230327c313431316f6967637c6f692e73656469756765646f63