Error Handling & Retry Rules Checklist

Q: How do I catch the right error in each SDK?

In boto3, catch ClientError and read err.response["Error"]["Code"]. In SDK v3, match typed exception classes with instanceof, or branch on error.name.

A remote call fails differently from a local one. It throttles, times out, and fails transiently over the network.

This checklist covers which errors to catch, which operations are safe to retry, and how to bound the retries so a blip does not become an outage or a bill.

How to Use This List

Each item is a checkbox rule with a short rationale; audit your own error handling against it.
Groups A through E run from "catch the right error" to "log for support."
The rules apply to both boto3 and AWS SDK for JavaScript v3; only the syntax of the catch differs.
The retry rules matter most for high-volume and long-running code, but the catching rules apply to every call.

A - Catch the Right Error

Catch typed errors, not bare exceptions. Handle ClientError in boto3 and typed exception classes in SDK v3 rather than a broad except Exception / catch (e).
Branch on the error code. Read err.response["Error"]["Code"] in boto3 and error.name in SDK v3, then decide per code.
Handle known recoverable cases explicitly. A missing object, a conditional-check failure, or an already-exists error is often normal flow, not a crash.
Re-raise the unexpected. If an error is not one you planned for, let it propagate; swallowing it hides real problems.
Do not parse error messages as strings. Match on the stable error code, not the human-readable message, which can change.

Match the specific error and read its code.

# --- Python (boto3) ---
from botocore.exceptions import ClientError
 
try:
    obj = s3.get_object(Bucket="reports", Key="q3.csv")
except ClientError as err:
    code = err.response["Error"]["Code"]
    if code == "NoSuchKey":
        obj = default_report()      # known, recoverable
    else:
        raise                       # surface the rest

// --- TypeScript (AWS SDK v3) ---
import { GetObjectCommand, NoSuchKey } from "@aws-sdk/client-s3";
 
try {
  var obj = await s3.send(new GetObjectCommand({ Bucket: "reports", Key: "q3.csv" }));
} catch (err) {
  if (err instanceof NoSuchKey) obj = defaultReport(); // known, recoverable
  else throw err;                                      // surface the rest
}

B - Classify Retryable vs Terminal

Retry throttling errors. ThrottlingException, TooManyRequestsException, and ProvisionedThroughputExceededException are transient and should back off and retry.
Retry transient 5xx and network errors. InternalError, ServiceUnavailable, timeouts, and connection resets are retryable.
Do not retry validation errors. ValidationException, InvalidParameterValue, and similar 4xx errors will fail identically every time; fix the input.
Do not retry access-denied or auth errors. AccessDenied and UnrecognizedClient mean permissions or credentials, not a transient blip.
Treat conditional-check failures as terminal. A ConditionalCheckFailedException is a business outcome to handle, not a call to retry.

C - Retry Only Idempotent Operations

Retry reads freely. Get, List, Describe, and Head operations are naturally idempotent and safe to retry.
Do not blindly retry non-idempotent writes. A retried SendMessage or Publish can create duplicates unless made idempotent.
Use idempotency tokens for creates. Pass a ClientRequestToken / clientToken so a retried create is deduplicated by the service.
Use conditional writes to make updates safe. A ConditionExpression (DynamoDB) or If-Match (S3) makes a repeated write a no-op instead of a double-apply.
Prefer PUT-style overwrites to append-style writes when retrying. An idempotent overwrite tolerates a retry; a blind append does not.

Pass an idempotency token so a retried create does not duplicate the resource.

# --- Python (boto3) ---
import uuid, boto3
 
sqs = boto3.client("sqs", region_name="us-east-1")
token = str(uuid.uuid4())  # stable across retries of THIS logical send
sqs.send_message(
    QueueUrl=queue_url,
    MessageBody="order-42",
    MessageDeduplicationId=token,   # FIFO queue dedupes retried sends
    MessageGroupId="orders",
)

// --- TypeScript (AWS SDK v3) ---
import { randomUUID } from "node:crypto";
import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";
 
const sqs = new SQSClient({ region: "us-east-1" });
const token = randomUUID(); // stable across retries of THIS logical send
await sqs.send(new SendMessageCommand({
  QueueUrl: queueUrl,
  MessageBody: "order-42",
  MessageDeduplicationId: token, // FIFO queue dedupes retried sends
  MessageGroupId: "orders",
}));

D - Bound and Configure Retries

Rely on the SDK's built-in retry. Both SDKs retry throttling and transient errors with exponential backoff by default; do not reimplement it.
Cap max attempts. Set Config(retries={"max_attempts": N}) in boto3 or maxAttempts: N in SDK v3; never retry an unbounded number of times.
Use adaptive retry mode for bursty load. Adaptive mode adds client-side rate limiting to standard backoff, easing sustained throttling.
Add jitter to any custom retry. If you must hand-roll a retry, use exponential backoff with jitter so clients do not synchronize into a thundering herd.
Set sensible timeouts. Configure connect and read timeouts so a hung socket fails fast enough to retry within your latency budget.

Configure retry behavior on the client, not in an ad-hoc loop.

# --- Python (boto3) ---
import boto3
from botocore.config import Config
 
cfg = Config(retries={"max_attempts": 5, "mode": "adaptive"})
ddb = boto3.client("dynamodb", region_name="us-east-1", config=cfg)

// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 
// maxAttempts caps total tries (1 initial + retries); adaptive mode adds rate limiting.
const ddb = new DynamoDBClient({ region: "us-east-1", maxAttempts: 5 });

E - Observe Failures

Log the request id on failure. Capture ResponseMetadata.RequestId (boto3) or $metadata.requestId (SDK v3) so AWS support can trace the call.
Log the error code and HTTP status. Record the stable code and status alongside the request id for triage.
Do not log the full request payload blindly. Redact secrets and PII before logging inputs.
Alert on retry exhaustion, not on individual retries. A single retried call is normal; exhausting the retry budget is the signal worth paging on.

FAQs

How do I catch the right error in each SDK?

In boto3, catch ClientError and read err.response["Error"]["Code"]. In SDK v3, match typed exception classes with instanceof, or branch on error.name.

Which errors are safe to retry?

Throttling errors and transient 5xx or network errors. Validation, access-denied, and conditional-check failures are terminal and will fail the same way again.

Why does idempotency matter for retries?

Because a retried write can duplicate work. An idempotency token or conditional write lets the service recognize the repeat and apply it only once.

Do I need to write my own retry loop?

Usually not. Both SDKs retry transient failures with backoff by default. Configure max_attempts / maxAttempts and a retry mode instead of hand-rolling a loop.

What is adaptive retry mode?

A retry mode that adds client-side rate limiting on top of standard exponential backoff, which helps when a service is throttling you under sustained load.

Why cap max attempts?

An unbounded retry loop hammers the API. Each attempt is billed and adds load, so a transient error that should cost one call can cost many.

Should I ever catch a bare exception?

Only at a top-level boundary to convert an unexpected failure into a clean response. Business logic should catch the specific typed error and re-raise the rest.

Why log the request id?

It uniquely identifies the call on the AWS side. When you open a support case or chase an intermittent failure, the request id is what lets AWS trace it.

How do I make a create retry-safe?

Pass a client request token (a stable UUID for the logical operation). If the create is retried, the service deduplicates on the token instead of creating twice.

What timeouts should I set?

Connect and read timeouts short enough that a hung socket fails within your latency budget, leaving room for the SDK to retry before the caller gives up.

Cost-Aware SDK Usage Rules - why unbounded retries and tight loops become a bill.
Resource Cleanup & Teardown Rules - releasing connections so failures do not leak resources.
Why AWS SDK Rules Exist - the reliability failure mode these rules address.
AWS SDK Rules & Best Practices Summary - the cross-cutting index for all checklists.

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

Error Handling & Retry Rules Checklist

A remote call fails differently from a local one. It throttles, times out, and fails transiently over the network.

This checklist covers which errors to catch, which operations are safe to retry, and how to bound the retries so a blip does not become an outage or a bill.

How to Use This List

Each item is a checkbox rule with a short rationale; audit your own error handling against it.
Groups A through E run from "catch the right error" to "log for support."
The rules apply to both boto3 and AWS SDK for JavaScript v3; only the syntax of the catch differs.
The retry rules matter most for high-volume and long-running code, but the catching rules apply to every call.

A - Catch the Right Error

Catch typed errors, not bare exceptions. Handle ClientError in boto3 and typed exception classes in SDK v3 rather than a broad except Exception / catch (e).
Branch on the error code. Read err.response["Error"]["Code"] in boto3 and error.name in SDK v3, then decide per code.
Handle known recoverable cases explicitly. A missing object, a conditional-check failure, or an already-exists error is often normal flow, not a crash.
Re-raise the unexpected. If an error is not one you planned for, let it propagate; swallowing it hides real problems.
Do not parse error messages as strings. Match on the stable error code, not the human-readable message, which can change.

Match the specific error and read its code.

# --- Python (boto3) ---
from botocore.exceptions import ClientError
 
try:
    obj = s3.get_object(Bucket="reports", Key="q3.csv")
except ClientError as err:
    code = err.response["Error"]["Code"]
    if code == "NoSuchKey":
        obj = default_report()      # known, recoverable
    else:
        raise                       # surface the rest

// --- TypeScript (AWS SDK v3) ---
import { GetObjectCommand, NoSuchKey } from "@aws-sdk/client-s3";
 
try {
  var obj = await s3.send(new GetObjectCommand({ Bucket: "reports", Key: "q3.csv" }));
} catch (err) {
  if (err instanceof NoSuchKey) obj = defaultReport(); // known, recoverable
  else throw err;                                      // surface the rest
}

B - Classify Retryable vs Terminal

Retry throttling errors. ThrottlingException, TooManyRequestsException, and ProvisionedThroughputExceededException are transient and should back off and retry.
Retry transient 5xx and network errors. InternalError, ServiceUnavailable, timeouts, and connection resets are retryable.
Do not retry validation errors. ValidationException, InvalidParameterValue, and similar 4xx errors will fail identically every time; fix the input.
Do not retry access-denied or auth errors. AccessDenied and UnrecognizedClient mean permissions or credentials, not a transient blip.
Treat conditional-check failures as terminal. A ConditionalCheckFailedException is a business outcome to handle, not a call to retry.

C - Retry Only Idempotent Operations

Retry reads freely. Get, List, Describe, and Head operations are naturally idempotent and safe to retry.
Do not blindly retry non-idempotent writes. A retried SendMessage or Publish can create duplicates unless made idempotent.
Use idempotency tokens for creates. Pass a ClientRequestToken / clientToken so a retried create is deduplicated by the service.
Use conditional writes to make updates safe. A ConditionExpression (DynamoDB) or If-Match (S3) makes a repeated write a no-op instead of a double-apply.
Prefer PUT-style overwrites to append-style writes when retrying. An idempotent overwrite tolerates a retry; a blind append does not.

Pass an idempotency token so a retried create does not duplicate the resource.

# --- Python (boto3) ---
import uuid, boto3
 
sqs = boto3.client("sqs", region_name="us-east-1")
token = str(uuid.uuid4())  # stable across retries of THIS logical send
sqs.send_message(
    QueueUrl=queue_url,
    MessageBody="order-42",
    MessageDeduplicationId=token,   # FIFO queue dedupes retried sends
    MessageGroupId="orders",
)

// --- TypeScript (AWS SDK v3) ---
import { randomUUID } from "node:crypto";
import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";
 
const sqs = new SQSClient({ region: "us-east-1" });
const token = randomUUID(); // stable across retries of THIS logical send
await sqs.send(new SendMessageCommand({
  QueueUrl: queueUrl,
  MessageBody: "order-42",
  MessageDeduplicationId: token, // FIFO queue dedupes retried sends
  MessageGroupId: "orders",
}));

D - Bound and Configure Retries

Rely on the SDK's built-in retry. Both SDKs retry throttling and transient errors with exponential backoff by default; do not reimplement it.
Cap max attempts. Set Config(retries={"max_attempts": N}) in boto3 or maxAttempts: N in SDK v3; never retry an unbounded number of times.
Use adaptive retry mode for bursty load. Adaptive mode adds client-side rate limiting to standard backoff, easing sustained throttling.
Add jitter to any custom retry. If you must hand-roll a retry, use exponential backoff with jitter so clients do not synchronize into a thundering herd.
Set sensible timeouts. Configure connect and read timeouts so a hung socket fails fast enough to retry within your latency budget.

Configure retry behavior on the client, not in an ad-hoc loop.

# --- Python (boto3) ---
import boto3
from botocore.config import Config
 
cfg = Config(retries={"max_attempts": 5, "mode": "adaptive"})
ddb = boto3.client("dynamodb", region_name="us-east-1", config=cfg)

// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 
// maxAttempts caps total tries (1 initial + retries); adaptive mode adds rate limiting.
const ddb = new DynamoDBClient({ region: "us-east-1", maxAttempts: 5 });

E - Observe Failures

Log the request id on failure. Capture ResponseMetadata.RequestId (boto3) or $metadata.requestId (SDK v3) so AWS support can trace the call.
Log the error code and HTTP status. Record the stable code and status alongside the request id for triage.
Do not log the full request payload blindly. Redact secrets and PII before logging inputs.
Alert on retry exhaustion, not on individual retries. A single retried call is normal; exhausting the retry budget is the signal worth paging on.

FAQs

How do I catch the right error in each SDK?

In boto3, catch ClientError and read err.response["Error"]["Code"]. In SDK v3, match typed exception classes with instanceof, or branch on error.name.

Which errors are safe to retry?

Throttling errors and transient 5xx or network errors. Validation, access-denied, and conditional-check failures are terminal and will fail the same way again.

Why does idempotency matter for retries?

Because a retried write can duplicate work. An idempotency token or conditional write lets the service recognize the repeat and apply it only once.

Do I need to write my own retry loop?

Usually not. Both SDKs retry transient failures with backoff by default. Configure max_attempts / maxAttempts and a retry mode instead of hand-rolling a loop.

What is adaptive retry mode?

A retry mode that adds client-side rate limiting on top of standard exponential backoff, which helps when a service is throttling you under sustained load.

Why cap max attempts?

An unbounded retry loop hammers the API. Each attempt is billed and adds load, so a transient error that should cost one call can cost many.

Should I ever catch a bare exception?

Only at a top-level boundary to convert an unexpected failure into a clean response. Business logic should catch the specific typed error and re-raise the rest.

Why log the request id?

It uniquely identifies the call on the AWS side. When you open a support case or chase an intermittent failure, the request id is what lets AWS trace it.

How do I make a create retry-safe?

Pass a client request token (a stable UUID for the logical operation). If the create is retried, the service deduplicates on the token instead of creating twice.

What timeouts should I set?

Connect and read timeouts short enough that a hung socket fails within your latency budget, leaving room for the SDK to retry before the caller gives up.

Cost-Aware SDK Usage Rules - why unbounded retries and tight loops become a bill.
Resource Cleanup & Teardown Rules - releasing connections so failures do not leak resources.
Why AWS SDK Rules Exist - the reliability failure mode these rules address.
AWS SDK Rules & Best Practices Summary - the cross-cutting index for all checklists.

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

Error Handling & Retry Rules Checklist

Search Documentation

Error Handling & Retry Rules Checklist