S3 throws S3Error for invalid configuration, documented vendor responses, malformed payloads, timeouts and network failures — one instanceof covers everything.

import { S3Error, S3ErrorCodes } from '@tundraconnect/s3/errors';

const error = new S3Error('NO_SUCH_KEY', { key: 'missing.txt' });
console.log(error.message);
console.log(S3ErrorCodes.NO_SUCH_KEY);

error.transient is true for exactly the codes marked yes above — TIMEOUT, NETWORK_ERROR, INTERNAL_ERROR, SERVICE_UNAVAILABLE and SLOW_DOWN (AWS documents InternalError and ServiceUnavailable as retryable) — and false for a definite refusal or a misconfiguration. Branch on it to tell "no answer yet, retry later" from "S3 said no". The set is also exported as S3_TRANSIENT_CODES from @tundraconnect/s3/errors.

if (error instanceof S3Error && error.transient) {
  // keep the job queued and try again later
}

Note that SERVICE_UNAVAILABLE is also the fallback for an error status with no recognizable <Error> body and no status mapping (for example a bodiless HEAD 400), so it is transient even in that rare case.

The resolved code is also available as a public, readonly error.code property — branch on failure mode without matching against .message:

if (error instanceof S3Error && error.code === 'NO_SUCH_KEY') {
  // ...
}

Use getContextValue() to read diagnostic metadata such as vendor, status, message (the vendor's own description), resource, requestId, bucket, key, cleanupError (a failed AbortMultipartUpload after a putObjectStream failure), timeoutSeconds (on TIMEOUT: the deadline that was missed), or originalCode. bucket/key are populated from the calling method's own arguments whenever they're known — including on NO_SUCH_KEY/NO_SUCH_BUCKET, whose message templates interpolate them.

S3 sends no body on a HEAD error response — only the status code is available. headObject therefore maps errors purely by HTTP status (404 → NO_SUCH_KEY, 403 → ACCESS_DENIED, ...), so a 404 caused by a missing bucket is still reported as NO_SUCH_KEY. Every other method (putObject, getObject, deleteObject, listObjects) gets S3's documented <Error> XML body and maps from the actual vendor Code.

A rate-limited request throws SLOW_DOWN. Two context values tell you what to do next:

Nothing is retried by default. Opt in with two client options (seconds, each 0–120):

• maxRetryWait — when a 429 carries a hint no longer than this, RESTler waits that long and retries once; otherwise it throws SLOW_DOWN immediately. 0 disables the retry.
• defaultRetryWait — the wait used when a 429 carries no hint. Without it a hintless 429 is never retried: RESTler does not invent a delay. Only consulted when maxRetryWait is set, and still capped by it.

Streamed downloads (getObjectStream()) follow the same rules as every other method (@tundralibs/restler >= 1.3.1).

← Back to S3