Errors

UploadStuffError

UploadStuffError is the error you throw from middleware or upload logic to reject a request with a specific HTTP status. It is exported from @upload-stuff/server.

import { UploadStuffError } from "@upload-stuff/server";

throw new UploadStuffError({
  code: "FORBIDDEN",
  message: "Sign in to upload",
  cause,
});

The instance carries a code, the message, and the status mapped from the code:

Codes and HTTP statuses

UploadStuffErrorCode is one of:

Response envelope

Every handled error response uses the same JSON envelope:

{ "error": "Sign in to upload" }

A thrown UploadStuffError responds with its mapped status. So do the handler's own 4xx guards — malformed JSON, request-shape validation failures, and unknown endpoints all return { "error": ... } with status 400. The Node handler additionally serializes unexpected errors as { "error": "Internal Server Error" } with status 500 — unless you pass next, in which case they are forwarded to your framework's error handling instead.

Client-side error handling

The client surfaces failures through the onUploadError callback, which receives a standard Error. For handled failures, error.message is the server's { error } string:

await client.uploadFiles("avatar", files, {
  onUploadError: (error) => {
    toast.error(error.message);
  },
});

uploadFiles — and the React startUpload — also reject with the same error after onUploadError runs, so attach a .catch (or await in a try/catch) to avoid unhandled rejections.

In React, pass the same callback to useUploadStuff. Aborting an in-flight upload triggers onUploadAborted rather than onUploadError.