AWS SDK Fundamentals Best Practices

Q: Why per-service clients in SDK v3?

The v3 SDK is modular. Importing only @aws-sdk/client- keeps your bundle and Lambda cold-start size small, which the monolithic approach cannot.

These are the habits that separate a quick script from code you can trust in production.

Walk the list once now, then treat it as a review checklist before shipping any AWS integration.

How to Use This List

Each item is a rule stated positively, with a one-line rationale.
Groups run roughly in order of impact: credentials and clients first, then errors, data, config, and cost.
Check the boxes against your own code as a quick audit.
Revisit when you add a new service client or move code to a new environment.

A - Credentials & Security

Never hardcode access keys. Let the SDK resolve credentials from its default chain (environment variables, shared config, IAM roles) so secrets stay out of source control.
Prefer IAM roles over long-lived keys. On EC2, ECS, and Lambda, attach a role; the SDK picks up temporary credentials automatically and rotates them.
Scope permissions to least privilege. Grant only the actions the code actually calls, so a leaked credential does limited damage.
Keep credentials out of logs. Do not print the resolved credential object or the Authorization header when debugging.

Let the default chain do the work rather than passing keys by hand.

# --- Python (boto3) ---
import boto3
 
# No keys in code: the default chain finds env vars, config, or an IAM role.
s3 = boto3.client("s3", region_name="us-east-1")

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
 
// No keys in code: the default provider chain resolves credentials.
const s3 = new S3Client({ region: "us-east-1" });

B - Client Lifecycle

Create clients once and reuse them. Client construction sets up connection pools and config; rebuilding per call wastes CPU and connections.
Use one client per service. Do not share a single client across unrelated services; make an S3 client and a DynamoDB client separately.
Install only the clients you need (SDK v3). Import @aws-sdk/client-<service> per service to keep bundles and Lambda cold starts small.
Share clients across handler invocations. In Lambda, initialize clients outside the handler so warm invocations reuse them.

C - Errors & Retries

Catch typed errors, not bare exceptions. Handle ClientError in boto3 and typed exception classes in SDK v3, and branch on the error code.
Rely on built-in retries for transient failures. Both SDKs retry throttling and network errors with backoff by default; do not reimplement this.
Tune retry mode for bursty workloads. Use adaptive or standard retry mode and a sane max attempt count instead of unlimited retries.
Log the request id on failure. Capture ResponseMetadata.RequestId (boto3) or $metadata.requestId (SDK v3) so AWS support can trace the call.

Match the specific error and read its code.

# --- Python (boto3) ---
from botocore.exceptions import ClientError
 
try:
    s3.get_object(Bucket="my-bucket", Key="missing.txt")
except ClientError as err:
    code = err.response["Error"]["Code"]
    rid = err.response["ResponseMetadata"]["RequestId"]
    print(code, rid)

// --- TypeScript (AWS SDK v3) ---
import { GetObjectCommand, NoSuchKey } from "@aws-sdk/client-s3";
 
try {
  await s3.send(new GetObjectCommand({ Bucket: "my-bucket", Key: "missing.txt" }));
} catch (err) {
  if (err instanceof NoSuchKey) console.log("NoSuchKey");
  else console.log((err as { $metadata?: { requestId?: string } }).$metadata?.requestId);
}

D - Data Access Patterns

Paginate with the built-in paginators. Use get_paginator (boto3) or paginate<Operation> helpers (SDK v3) instead of managing continuation tokens by hand.
Filter server-side. Pass a Prefix, KeyConditionExpression, or FilterExpression so you fetch only what you need.
Batch multi-item work. Prefer BatchGetItem and BatchWriteItem over one call per item to cut requests and latency.
Stream large payloads. Upload and download large objects as streams rather than buffering them fully in memory.

E - Configuration & Region

Set the region explicitly. Pin region_name / region (or AWS_REGION) so behavior does not depend on ambient defaults.
Do not hardcode endpoint URLs. Let the SDK resolve endpoints; use dual-stack or FIPS flags when required rather than literal hostnames.
Override endpoints only for local testing. Point at LocalStack in tests, never freeze a production endpoint string.
Do not assume the aws partition. Build ARNs from the request context, since GovCloud and China use different partition segments.

F - Cost & Reliability

Avoid tight polling loops. Use waiters or poll with backoff and a max attempt count.
Cache read-heavy, slow-changing data. A short-lived cache cuts repeated identical reads and their per-request cost.
Set budgets and alarms. Configure AWS Budgets and billing alarms so runaway loops surface before the invoice does.
Prefer events over polling. Use SNS, SQS, or EventBridge so changes notify your code instead of you asking repeatedly.

FAQs

Why is client reuse the first thing to fix?

Because rebuilding a client per call is a common, silent waste. Construction sets up connection pools and configuration, so reusing one client across requests is cheaper and faster.

Why never hardcode credentials?

Hardcoded keys leak into source control and logs, are hard to rotate, and grant standing access. The default credential chain uses environment, config, and rotating IAM role credentials instead.

Should I write my own retry logic?

Usually no. Both SDKs retry transient and throttling errors with backoff by default. Tune the retry mode and max attempts instead of reimplementing retries yourself.

When should I skip the pagination rule?

Only when an operation returns a single, bounded result with no continuation token. Any list operation that can return a token should use a paginator.

Why log the request id?

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

Why set the region explicitly?

Ambient region defaults differ across machines and environments. Pinning the region makes behavior reproducible and avoids calls silently going to the wrong region.

Is least privilege really a fundamentals concern?

Yes. Over-broad permissions turn a minor credential leak into a major incident. Scoping actions to what the code calls is a baseline habit, not an advanced one.

What is the single biggest cost mistake?

Unbounded loops and tight polling. They turn one logical action into thousands of billed requests, so use waiters, batching, and events instead.

Why per-service clients in SDK v3?

The v3 SDK is modular. Importing only @aws-sdk/client-<service> keeps your bundle and Lambda cold-start size small, which the monolithic approach cannot.

Should I ever override the endpoint?

Only for local testing against tools like LocalStack. In production, overriding disables endpoint resolution and freezes the partition, which breaks portability.

How do I catch the right error?

In boto3, catch ClientError and read err.response["Error"]["Code"]. In SDK v3, match typed exception classes with instanceof, such as NoSuchKey.

Where should I initialize clients in Lambda?

Outside the handler function, at module scope. Warm invocations then reuse the same client instead of constructing a new one on every request.

AWS SDK Fundamentals Basics - the calls these habits apply to.
How AWS Bills SDK Calls - the cost rules in group F, in depth.
Anatomy of an AWS API Request - why the request id and signing matter.
Service Endpoints, Partitions & Dual-Stack/FIPS Variants - the region and endpoint rules in group E.

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

AWS SDK Fundamentals Best Practices

These are the habits that separate a quick script from code you can trust in production.

Walk the list once now, then treat it as a review checklist before shipping any AWS integration.

How to Use This List

Each item is a rule stated positively, with a one-line rationale.
Groups run roughly in order of impact: credentials and clients first, then errors, data, config, and cost.
Check the boxes against your own code as a quick audit.
Revisit when you add a new service client or move code to a new environment.

A - Credentials & Security

Never hardcode access keys. Let the SDK resolve credentials from its default chain (environment variables, shared config, IAM roles) so secrets stay out of source control.
Prefer IAM roles over long-lived keys. On EC2, ECS, and Lambda, attach a role; the SDK picks up temporary credentials automatically and rotates them.
Scope permissions to least privilege. Grant only the actions the code actually calls, so a leaked credential does limited damage.
Keep credentials out of logs. Do not print the resolved credential object or the Authorization header when debugging.

Let the default chain do the work rather than passing keys by hand.

# --- Python (boto3) ---
import boto3
 
# No keys in code: the default chain finds env vars, config, or an IAM role.
s3 = boto3.client("s3", region_name="us-east-1")

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
 
// No keys in code: the default provider chain resolves credentials.
const s3 = new S3Client({ region: "us-east-1" });

B - Client Lifecycle

Create clients once and reuse them. Client construction sets up connection pools and config; rebuilding per call wastes CPU and connections.
Use one client per service. Do not share a single client across unrelated services; make an S3 client and a DynamoDB client separately.
Install only the clients you need (SDK v3). Import @aws-sdk/client-<service> per service to keep bundles and Lambda cold starts small.
Share clients across handler invocations. In Lambda, initialize clients outside the handler so warm invocations reuse them.

C - Errors & Retries

Catch typed errors, not bare exceptions. Handle ClientError in boto3 and typed exception classes in SDK v3, and branch on the error code.
Rely on built-in retries for transient failures. Both SDKs retry throttling and network errors with backoff by default; do not reimplement this.
Tune retry mode for bursty workloads. Use adaptive or standard retry mode and a sane max attempt count instead of unlimited retries.
Log the request id on failure. Capture ResponseMetadata.RequestId (boto3) or $metadata.requestId (SDK v3) so AWS support can trace the call.

Match the specific error and read its code.

# --- Python (boto3) ---
from botocore.exceptions import ClientError
 
try:
    s3.get_object(Bucket="my-bucket", Key="missing.txt")
except ClientError as err:
    code = err.response["Error"]["Code"]
    rid = err.response["ResponseMetadata"]["RequestId"]
    print(code, rid)

// --- TypeScript (AWS SDK v3) ---
import { GetObjectCommand, NoSuchKey } from "@aws-sdk/client-s3";
 
try {
  await s3.send(new GetObjectCommand({ Bucket: "my-bucket", Key: "missing.txt" }));
} catch (err) {
  if (err instanceof NoSuchKey) console.log("NoSuchKey");
  else console.log((err as { $metadata?: { requestId?: string } }).$metadata?.requestId);
}

D - Data Access Patterns

Paginate with the built-in paginators. Use get_paginator (boto3) or paginate<Operation> helpers (SDK v3) instead of managing continuation tokens by hand.
Filter server-side. Pass a Prefix, KeyConditionExpression, or FilterExpression so you fetch only what you need.
Batch multi-item work. Prefer BatchGetItem and BatchWriteItem over one call per item to cut requests and latency.
Stream large payloads. Upload and download large objects as streams rather than buffering them fully in memory.

E - Configuration & Region

Set the region explicitly. Pin region_name / region (or AWS_REGION) so behavior does not depend on ambient defaults.
Do not hardcode endpoint URLs. Let the SDK resolve endpoints; use dual-stack or FIPS flags when required rather than literal hostnames.
Override endpoints only for local testing. Point at LocalStack in tests, never freeze a production endpoint string.
Do not assume the aws partition. Build ARNs from the request context, since GovCloud and China use different partition segments.

F - Cost & Reliability

Avoid tight polling loops. Use waiters or poll with backoff and a max attempt count.
Cache read-heavy, slow-changing data. A short-lived cache cuts repeated identical reads and their per-request cost.
Set budgets and alarms. Configure AWS Budgets and billing alarms so runaway loops surface before the invoice does.
Prefer events over polling. Use SNS, SQS, or EventBridge so changes notify your code instead of you asking repeatedly.

FAQs

Why is client reuse the first thing to fix?

Because rebuilding a client per call is a common, silent waste. Construction sets up connection pools and configuration, so reusing one client across requests is cheaper and faster.

Why never hardcode credentials?

Hardcoded keys leak into source control and logs, are hard to rotate, and grant standing access. The default credential chain uses environment, config, and rotating IAM role credentials instead.

Should I write my own retry logic?

Usually no. Both SDKs retry transient and throttling errors with backoff by default. Tune the retry mode and max attempts instead of reimplementing retries yourself.

When should I skip the pagination rule?

Only when an operation returns a single, bounded result with no continuation token. Any list operation that can return a token should use a paginator.

Why log the request id?

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

Why set the region explicitly?

Ambient region defaults differ across machines and environments. Pinning the region makes behavior reproducible and avoids calls silently going to the wrong region.

Is least privilege really a fundamentals concern?

Yes. Over-broad permissions turn a minor credential leak into a major incident. Scoping actions to what the code calls is a baseline habit, not an advanced one.

What is the single biggest cost mistake?

Unbounded loops and tight polling. They turn one logical action into thousands of billed requests, so use waiters, batching, and events instead.

Why per-service clients in SDK v3?

The v3 SDK is modular. Importing only @aws-sdk/client-<service> keeps your bundle and Lambda cold-start size small, which the monolithic approach cannot.

Should I ever override the endpoint?

Only for local testing against tools like LocalStack. In production, overriding disables endpoint resolution and freezes the partition, which breaks portability.

How do I catch the right error?

In boto3, catch ClientError and read err.response["Error"]["Code"]. In SDK v3, match typed exception classes with instanceof, such as NoSuchKey.

Where should I initialize clients in Lambda?

Outside the handler function, at module scope. Warm invocations then reuse the same client instead of constructing a new one on every request.

AWS SDK Fundamentals Basics - the calls these habits apply to.
How AWS Bills SDK Calls - the cost rules in group F, in depth.
Anatomy of an AWS API Request - why the request id and signing matter.
Service Endpoints, Partitions & Dual-Stack/FIPS Variants - the region and endpoint rules in group E.

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

AWS SDK Fundamentals Best Practices

Buscar en la documentación

AWS SDK Fundamentals Best Practices