Errors

Every single-key method throws a FilesError on failure. It collapses the dozens of provider-specific error shapes into one type with a small code enum, while keeping the original error on cause so nothing is lost.

import { FilesError } from "files-sdk";

try {
  await files.download("missing.png");
} catch (err) {
  if (err instanceof FilesError && err.code === "NotFound") {
    // handle gracefully
    return null;
  }
  throw err;
}

Properties

• code — one of the four normalized codes below. Match on this for control flow.
• message — a human-readable summary, taken from the provider error where one is available.
• cause — the original provider error, untouched. Reach into it for provider-specific detail: @aws-sdk errors, for instance, carry a request ID and HTTP status on $metadata and a typed name like NoSuchKey.
• aborted — true when the failure came from a cancellation or a timeout rather than the provider. Both surface as code: "Provider", so this flag is how you tell an abort apart from a genuine provider failure.

Codes

• "NotFound" — the key (or bucket / container) does not exist.
• "Unauthorized" — credentials missing, expired, or insufficient for the operation.
• "Conflict" — a precondition failed, e.g. a conditional write that lost a race.
• "Provider" — anything else, including network failures, throttling, timeouts, and aborts. Inspect cause for the underlying error.

Codes are derived from the provider's own error code and HTTP status: 404 maps to NotFound, 401 / 403 to Unauthorized, 409 / 412 to Conflict, and everything else to Provider. Only Provider failures are retried; the rest are deterministic and returned to you immediately.

Errors in bulk operations

The array forms — upload([…]), download([…]), delete([…]), head([…]), exists([…]) — don't throw on partial failure. Each resolves to a structured result that collects per-key failures in an errors[] array (each entry a { key, error: FilesError }) alongside the successes, both in the order you supplied. One bad key never sinks the whole batch. See each method's page for the exact result shape.

Logging note: cause can carry request IDs, response headers, and partial request metadata from @aws-sdk and friends. If you forward a FilesError to logs that cross a trust boundary, strip or whitelist cause rather than JSON.stringify-ing the whole thing.

For provider-by-provider error gotchas and debugging tips, see Troubleshooting.