Requests and responses
Objective
Section titled “Objective”Read this page to construct a request by hand, or to understand what your SDK is doing for you.
Requirements
Section titled “Requirements”- An access key id and secret access key
Instructions
Section titled “Instructions”Protocol
Section titled “Protocol”HTTPS, HTTP/1.1 or HTTP/2. Each service uses the wire protocol its AWS counterpart uses, because matching it is what makes existing clients work:
| Service | Protocol | Request | Response |
|---|---|---|---|
| EC2 | Query | Form-encoded POST, or GET | XML |
| IAM | Query | Form-encoded POST | XML |
| Account | JSON | JSON POST, action in X-Shelf-Target | JSON |
| Billing | JSON | JSON POST, action in X-Shelf-Target | JSON |
There is no content negotiation. A service speaks one protocol.
Required request headers
Section titled “Required request headers”| Header | Purpose |
|---|---|
Authorization | The SigV4 signature |
X-Amz-Date | Request timestamp, ISO 8601 basic |
Host | Signed; must match the endpoint |
Content-Type | As the service requires |
Response headers
Section titled “Response headers”| Header | Purpose |
|---|---|
x-amzn-RequestId | The request id, on every response |
Date | Our clock, for skew detection |
x-amzn-ErrorType | The error code, on JSON-service errors |
x-amzn-RequestId is the header the AWS SDKs read to populate response
metadata. It is emitted on success and on failure, including on authentication
failures.
Request ids
Section titled “Request ids”Every request has an id. It is the only thing support needs to find a call in our records, and it is returned in the header above and in the response body for query-protocol services.
PROPOSED: request ids are retained for 90 days.
That retention is shorter than the retention of usage records, deliberately, and the difference has a consequence worth stating: a billing dispute raised about a period older than 90 days can be resolved from usage records but not from request logs.
OPEN (Michael): maximum request body size, header size, and URL length.
Compression
Section titled “Compression”PROPOSED: gzip accepted on requests and offered on responses when the
client advertises it.
Redirects
Section titled “Redirects”Never. An endpoint answers or returns an error. A redirect would invite a client to re-send a signed request to a host it did not intend to call, and the host is part of the signature.
Retries
Section titled “Retries”Retry on 500, 502, 503 and 504, and on the throttling code for that service, with exponential backoff and jitter.
Do not retry a 4xx — except the eventual-consistency case below.
Eventual consistency
Section titled “Eventual consistency”A resource that has just been created may not be visible to an immediately following call. A describe issued moments after a create may return a not-found error for a resource that does exist.
This is inherited from Amazon EC2, whose own documentation instructs callers to
allow for it, and existing tooling already does: the Terraform AWS provider
retries InvalidInstanceID.NotFound, InvalidGroup.NotFound and
InvalidVpcID.NotFound for exactly this reason.
So: retry a not-found error for a resource created within the last few seconds. This is the one documented exception to the rule that a 4xx is not retryable, and a client that follows the general rule without this exception will fail intermittently under load.
PROPOSED: a created resource is visible to all readers within 10 seconds.
OPEN (Michael): whether any operation offers read-after-write consistency, and if so which. Every service that does not must carry a propagation note on its create operations.
Throttling
Section titled “Throttling”Each service documents its own throttling code and status; they differ, and the errors page explains why.
OPEN (Michael): per-account request rates, per service.
A throttled response carries a distinct code rather than a generic error, so that a client can distinguish “slow down” from “this will never work”.