Search across all documentation pages
Coding standards for AWS SDK code are narrower than general style guides. They cover four things that recur in every integration: how clients and variables are named, how errors are caught and classified, how clients are constructed and reused, and whether the code is type-checked.
Getting these four right once, in writing, prevents the slow drift described in Why AWS SDK Code Needs Governance - the same operation implemented three different ways across three different files.
Quick-reference recipe card - copy-paste ready.
# --- Python (boto3) ---
# Naming: <service>_client, module-level, built once
import boto3
from botocore.exceptions import ClientError
s3_client = boto3.client("s3", region_name="us-east-1")
def is_not_found(err: ClientError) -> bool:
return err.response["Error"]["Code"] in ("NoSuchKey", "404")// --- TypeScript (AWS SDK v3) ---
// Naming: <service>Client, module-level, built once
import { S3Client } from "@aws-sdk/client-s3";
export const s3Client = new S3Client({ region: "us-east-1" });
export function isNotFound(err: unknown): boolean {
return err instanceof Error && err.name === "NotFound";
}When to reach for this:
A small module showing the four conventions applied together: a module-level client, a naming pattern, a shared error classifier, and typed imports.
# --- Python (boto3) ---
# reports_client.py
import boto3
from botocore.exceptions import ClientError
from mypy_boto3_s3 import S3Client
s3_client: S3Client = boto3.client("s3", region_name="us-east-1")
def is_not_found(err: ClientError) -> bool:
return err.response["Error"]["Code"] in ("NoSuchKey", "404")
def read_report(bucket: str, key: str) -> bytes | None:
try:
obj = s3_client.get_object(Bucket=bucket, Key=key)
return obj["Body"].read()
except ClientError as err:
if is_not_found(err):
return None
raise// --- TypeScript (AWS SDK v3) ---
// reportsClient.ts
import { S3Client, GetObjectCommand, NoSuchKey } from "@aws-sdk/client-s3";
export const s3Client = new S3Client({ region: "us-east-1" });
export function isNotFound(err: unknown): boolean {
return err instanceof NoSuchKey;
}
export async function readReport(
bucket: string,
key: string,
): Promise<Uint8Array | null> {
try {
const obj = await s3Client.send(
new GetObjectCommand({ Bucket: bucket, Key: key }),
);
return await obj.Body!.transformToByteArray();
} catch (err) {
if (isNotFound(err)) return null;
throw err;
}
}What this demonstrates:
s3_client / s3Client) is built once, at module load, and imported wherever it's needed - never constructed fresh per call.is_not_found / isNotFound), so every caller shares the same definition of "not found."mypy_boto3_s3 in Python and natively from @aws-sdk/client-s3 in TypeScript, so a wrong field name is a type error, not a runtime surprise.<service>_client / <service>Client) makes the module readable without opening its imports.Pick one pattern and apply it everywhere: snake_case client and variable names in Python (s3_client, dynamodb_client), camelCase in TypeScript (s3Client, dynamoDbClient), each matching the language's own idiom rather than forcing one language's convention onto the other.
The convention itself matters less than its consistency. A reviewer who sees s3 in one file and s3Client2 in another is looking at drift, not a style choice.
boto3 raises botocore.exceptions.ClientError for every API-level error, with the specific error code nested at err.response["Error"]["Code"]. AWS SDK for JavaScript v3 throws typed exception classes per service (NoSuchKey, ThrottlingException, and so on) that you match with instanceof.
The standard is not to re-derive this mechanism at every call site, but to centralize the classification - "is this error retryable, is this error a expected not-found case" - in one shared helper per error category, imported everywhere it's needed. The mechanics of catching and retrying errors correctly are already covered in this cookbook's pagination-and-retries and debugging sections; the standard here is applying those mechanics the same way across the codebase, not reinventing them.
Both SDKs are designed for a client to be built once and reused across many calls. In boto3, boto3.client("s3") does no network work by itself and is safe to hold at module scope. In SDK v3, new S3Client({}) is similarly cheap to construct and expensive to recreate per request, since each new client re-initializes its middleware stack and connection pool.
The standard: build clients at module load (or once per Lambda cold start, outside the handler), never inside a request handler or a loop. This is covered mechanically in sdk-mechanics; the coding standard is simply to enforce it as a rule, not leave it to individual judgment.
Python's boto3 and botocore are not natively typed; typed clients come from installing boto3-stubs/mypy-boto3 per service, already covered in boto3-fundamentals. TypeScript's @aws-sdk/client-* packages ship their own types, so no extra install is needed.
The standard is to require type checking on new code by default in both languages - mypy or pyright in CI for Python, tsc --noEmit for TypeScript - rather than treating it as optional tooling a developer may or may not turn on.
A written standard only holds if something checks it. A ruff or mypy config in Python, and an eslint config in TypeScript, catch naming and typing violations automatically in CI, which scales better than relying on every reviewer to remember every rule.
# pyproject.toml (Python - ruff config excerpt)
[tool.ruff]
line-length = 100
[tool.ruff.lint]
select = ["E", "F", "N"] # includes naming (N) checks// .eslintrc.json (TypeScript - excerpt)
{
"rules": {
"camelcase": ["error", { "properties": "never" }],
"@typescript-eslint/no-explicit-any": "warn"
}
}These configs are language-specific tooling, not SDK code, so each is shown once rather than paired side by side.
Exception/generic error instead of the typed one. Hides which failure actually happened and can swallow bugs unrelated to AWS. Fix: catch ClientError (Python) or the specific typed exception (TypeScript), and branch on the error code.boto3-stubs; skipping it means missing the same errors TypeScript would catch for free. Fix: install the relevant boto3-stubs service extra and enable mypy/pyright in CI.s3 next to s3_client2 next to S3 makes the code harder to scan. Fix: pick one pattern, write it down, and enforce it with a linter naming rule.| Alternative | Use When | Don't Use When |
|---|---|---|
| A written standard only, no linter enforcement | A very small team or prototype, low review overhead | Multiple contributors, since unenforced standards drift within weeks |
| Linter-enforced standard (ruff/mypy, eslint) | Any team with more than one contributor or an active CI pipeline | You have no CI at all and a linter would go unrun |
Per-service typed clients (boto3-stubs[s3,dynamodb]) | You use a known, stable set of services | You call so many services that installing every stub extra becomes its own maintenance task; consider the broader boto3-stubs[all] extra there |
| Centralized error-helper module | Multiple call sites need the same error classification | A one-off script with a single call site, where the overhead isn't worth it |
No. Match each language's own idiom - snake_case in Python, camelCase in TypeScript. The goal is internal consistency within each codebase, not identical spelling across languages.
In one shared helper per error category, imported by every call site that needs it. This is a coding-standards concern about organization, not a change to the underlying retry/error-handling mechanics covered elsewhere in this cookbook.
Rarely. It adds latency and discards connection reuse. The only common exception is short-lived scripts where a single client is constructed once anyway, which already satisfies the standard.
Less benefit without a type checker, since IDEs use the stubs for autocomplete too, but the enforcement value comes from running mypy/pyright in CI. Install the stubs either way; wire up the checker when you can.
Put naming and typing checks in a linter config that runs in CI, so violations are caught automatically rather than relying on a human reviewer to remember every rule.
No. The pagination-and-retries and debugging sections cover the mechanics - what to catch, when to retry. This page covers applying those mechanics consistently across a codebase.
Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).
Reviewed by Chris St. John·Last updated Jul 23, 2026