AWS API Basics for Developers: Regions, Retries, Exponential Backoff, Pagination and Error Handling

AWS Developer Associate 40 min min read Updated: Nov 17, 2026 Intermediate
AWS API Basics for Developers: Regions, Retries, Exponential Backoff, Pagination and Error Handling
Intermediate Topic 3 of 3

How an AWS API Call Works

  1. Your code calls the SDK, for example s3.put_object
  2. The SDK builds an HTTPS request to the regional endpoint (such as s3.ap-south-1.amazonaws.com)
  3. It signs the request with Signature Version 4 using your credentials. The signature proves who you are and that the request was not changed
  4. AWS checks authentication and IAM authorization, runs the action and returns JSON or XML
  5. The SDK turns errors into exceptions

The SDK and CLI sign automatically. You only sign by hand when calling an AWS API with plain HTTP. Presigned URLs also use SigV4 and carry the signature in the query string.

Error Types

Code rangeMeaningRetry?
4xx (client errors)Your request is wrong: bad parameter, AccessDenied, ResourceNotFoundException, validation errorNo (fix the request)
429 / Throttling (ThrottlingException, ProvisionedThroughputExceededException, TooManyRequestsException, SlowDown)Too many requestsYes with backoff
5xx (server errors)Service problem: InternalError, ServiceUnavailableYes with backoff
Timeouts and connection errorsNetwork or overloaded serviceYes, if the operation is safe to repeat

Exponential Backoff with Jitter

If many clients retry at the same moment they overload the service again. Exponential backoff waits longer after each failure (for example 100 ms, 200 ms, 400 ms, up to a cap). Jitter adds randomness so clients do not retry in lockstep.

text wait = random(0, min(cap, base * 2 ** attempt)) # "full jitter" attempt 1 -> up to 200 ms attempt 2 -> up to 400 ms attempt 3 -> up to 800 ms ... until max attempts

You rarely write this yourself. AWS SDKs already retry throttling and transient errors with backoff. You tune the settings.

python import boto3 from botocore.config import Config cfg = Config( region_name="ap-south-1", retries={"max_attempts": 8, "mode": "adaptive"}, # modes: legacy, standard, adaptive connect_timeout=3, read_timeout=10, ) ddb = boto3.client("dynamodb", config=cfg)
Retry modeBehavior
legacyOlder default, fewer error types retried
standardConsistent across SDKs, backoff with jitter, retry quota
adaptiveStandard plus client-side rate limiting that slows down when throttled
  • Set timeouts. The defaults can be long and hold threads
  • Retry only idempotent operations safely. For others use an idempotency token (many APIs accept ClientToken or ClientRequestToken) so a repeated request does not create duplicates
  • Put a limit on total retry time inside Lambda so you do not run into the function timeout
  • For messages that keep failing use a dead-letter queue instead of infinite retries

Pagination

List APIs return pages. If a response has a NextToken, Marker or LastEvaluatedKey, there is more data. Ignoring this is a classic bug: you process only the first page (for example 1,000 S3 objects or 1 MB of DynamoDB results).

python import boto3 s3 = boto3.client("s3") paginator = s3.get_paginator("list_objects_v2") total = 0 for page in paginator.paginate(Bucket="my-bucket", Prefix="logs/", PaginationConfig={"PageSize": 500}): for obj in page.get("Contents", []): total += obj["Size"] print("bytes:", total)
bash aws s3api list-objects-v2 --bucket my-bucket --max-items 100 # returns NextToken aws s3api list-objects-v2 --bucket my-bucket --starting-token "eyJ..." # continue

Waiters

A waiter polls until a resource reaches a state, with sensible delays and a maximum wait. It replaces hand-written sleep loops.

python ec2 = boto3.client("ec2") ec2.get_waiter("instance_running").wait( InstanceIds=["i-0abc123"], WaiterConfig={"Delay": 10, "MaxAttempts": 30}) print("ready")

Handling Errors in Code

python import boto3 from botocore.exceptions import ClientError s3 = boto3.client("s3") try: s3.head_object(Bucket="my-bucket", Key="a.txt") except ClientError as e: code = e.response["Error"]["Code"] if code in ("404", "NoSuchKey", "NotFound"): print("missing") elif code in ("403", "AccessDenied"): raise PermissionError("check IAM and bucket policy") from e else: raise
  • Use e.response['Error']['Code'] and e.response['ResponseMetadata']['HTTPStatusCode']
  • Log the request id (ResponseMetadata.RequestId) so AWS Support can trace the call
  • Do not swallow all exceptions

Batching and Limits

ServiceBatch APILimit to remember
DynamoDBBatchGetItem, BatchWriteItem100 reads / 25 writes per call. Handle UnprocessedItems
SQSSendMessageBatch, DeleteMessageBatch10 messages per call
SNSPublishBatch10 messages
KinesisPutRecords500 records, 5 MB. Check FailedRecordCount
S3Multipart upload; delete up to 1000 keys per requestParts 5 MB to 5 GB

Batch calls can partially fail. Always inspect the response for unprocessed or failed entries and retry only those.

Practice Tasks

  1. Configure a client with adaptive retries and short timeouts
  2. List all objects of a large bucket with a paginator
  3. Wait for an EC2 instance with a waiter
  4. Write a BatchWriteItem call that retries UnprocessedItems with backoff
  5. Trigger a throttling error on a low-capacity DynamoDB table and watch the SDK retry

Conclusion

AWS calls are signed HTTPS requests to regional endpoints. Retry throttling and 5xx errors with exponential backoff and jitter (the SDK does this), never blindly retry 4xx errors, use paginators and waiters, set timeouts, use idempotency tokens, and check batch responses for partial failures.

Quick Summary: API call flow; error types; backoff + jitter; retry modes; pagination; waiters; error handling code; batching limits.

Get Newsletter

Subscibe to our newsletter and we will notify you about the newest updates on Edugators