Errors - Upstash Documentation

app/avatar.py

from upstash_blob import BlobError, BlobInfo, Bucketbucket = Bucket.from_env()def avatar(path: str) -> BlobInfo | None:    try:        return bucket.info(path)    except BlobError as e:        if e.code == "not_found":            return None        raise

Every failure the SDK reports is a BlobError, an Exception subclass. Its codes are the ones the TypeScript SDK and the browser client use, so an error raised in your Python handler reaches a React hook with its code intact. The codes, their statuses and when each one is raised are on Errors.

BlobError and BlobErrorCode are exported from upstash_blob.

Catching it#

try:    bucket.put(path, body, max_size="5mb")except BlobError as e:    e.code     # BlobErrorCode, e.g. 'too_large'    e.status   # int, e.g. 413    e.message  # str, the same as str(e)

There is one BlobError class, so except BlobError and isinstance are all you need. BlobErrorCode is a Literal of every code, so an editor completes them.

Fields#

try:    bucket.delete(["a.png", "b.png", "c.png"])except BlobError as e:    if e.code == "partial_delete":        queue_for_retry(e.failed or [])    elif e.code == "mint_backoff":        retry_later(after=e.retry_after)    else:        raise

Field	Type	Set by
`code`	`BlobErrorCode`	Always. One of the codes.
`status`	`int`	Always.
`message`	`str`	Always. See Messages.
`hint`	`str \| None`	Any code. See Hints.
`failed`	`list[str] \| None`	`partial_delete`: the paths that survived the delete.
`etag`	`str \| None`	`already_exists`: the etag of what is already there.
`size`	`int \| None`	`already_exists`: the size of what is already there.
`retry_after`	`float \| None`	`mint_backoff`: seconds the credential service asked the caller to wait. On another code, only when you set it yourself.
`reason`	`str \| None`	A refusal from Upstash meant for the bucket owner, such as a suspended or read-only bucket. Never in `message` or `to_dict()`.

The underlying error, when there was one, is the standard __cause__, set with raise ... from. A move_left_a_copy carries the failed delete there.

Built-in hints#

BlobError("length_required").message# 'Length required (pass size= or max_size= so the length is known before the first byte)'

Code	Built-in hint
`signature_mismatch`	the upload did not match what was authorized, usually a different size or content type
`length_required`	pass `size=` or `max_size=` so the length is known before the first byte

How a hint folds into the message is on Hints fold into the message.

Raising one#

BlobError("not_found").message                      # 'Not found'BlobError("forbidden", "not your thread").message    # 'Not your thread'BlobError("too_large", "you are out of space")BlobError("rate_limited", retry_after=30)

BlobError(code, message=None, *, hint, status, failed, etag, size, retry_after, reason). The message is positional; everything else is a keyword. Raise one from an upload handler callback to refuse an upload with that code; see Refusing.

to_dict()#

BlobError("too_large", "cat.png is 3.1 MB, over the 2 MB limit").to_dict()# {'code': 'too_large', 'message': 'cat.png is 3.1 MB, over the 2 MB limit', 'status': 413}

The JSON body an upload route answers a refusal with, and what the browser client rebuilds into its own BlobError. hint, failed, etag, size and retryAfter are included when they are set. reason never is.

The handler writes this body for you. Call it yourself to answer with a BlobError from a route of your own, such as one that calls put for useServerUpload:

app/main.py

from fastapi.responses import JSONResponsetry:    blob = await bucket.put(path, file.file, max_size="2mb")except BlobError as e:    return JSONResponse(e.to_dict(), status_code=e.status)

A BlobError also survives pickle, so it crosses a process pool or a task queue with its fields intact.

Bad options raise TypeError or ValueError#

A wrong type raises a TypeError and a value that does not parse raises a ValueError, where the option is written:

Mistake	Raises
`Bucket.from_env()` with the variable unset	`TypeError`
`retry={"retrys": 3}`, `content_types="image/*"`, `max_size=True`	`TypeError`
`max_size="5mbit"`, `expires_in="soon"`, a negative size	`ValueError`
A path that is empty or has a `.` or `..` segment, on any `Bucket` method	`ValueError`
An upload handler with no `on_before_upload`, an empty `routes`, a bad route name	`TypeError`, when the handler is built
A body of an unsupported type, or one that yields `str`	`TypeError`
`cache="forever"` on `Bucket(...)`	`ValueError`, from each call that stores an object

Two option mistakes raise a BlobError instead. A content_types list that is empty, or holds an entry that is not a type/subtype or one of image/*, video/* and audio/*, raises invalid_content_type_pattern, on a put or when a handler is built. A content_type that is not a media type raises invalid_input.

The upload handler turns the path errors into invalid_input, since a path built from the browser’s filename can be the client’s doing. A few handler mistakes only show up while a request runs, and raise a TypeError that the framework answers as a 500:

on_before_upload returned something other than a BeforeUploadResult, or a state that is not JSON-serializable.
on_before_upload returned content_types or a max_size wider than the route’s; see Narrowing per user.
on_upload_complete returned a value that is not JSON-serializable.
An UploadHandler callback returned a coroutine; see Sync or async.