Reference

Errors

There are no error codes to memorize — the HTTP status is the contract, and the body is one human-readable message in a fixed envelope:

json400 Bad Request

{
  "error": "ttl must be an integer number of seconds (min 60)"
}

Status catalogue

Status	When
400`bad request`	Unparseable bodies, bad paths, invalid `ttl`/`name` values, per-request file caps, invalid zips.
401`unauthorized`	Account routes without a credential, `?name=` without a key, minting keys without an ID token.
402`payment required`	Subscriber features (`?name=`, long `ttl`, append, vanity) on a free account.
404`not found`	Missing drops, keys or files — also returned for resources owned by someone else.
405`method not allowed`	Wrong verb on a real path, e.g. POSTing to a served drop.
409`conflict`	Vanity sub already taken, or the account already owns one.
410`gone`	The drop expired — see Expiry. Browsers get an “expired” page.
413`payload too large`	Zip over the plan cap, decompression past 4×, or a drop hitting its 10,000-file total.
429`rate limited`	10 deploys/min per IP anonymous, 120/min per account subscribed.
451`unavailable for legal reasons`	The drop was taken down — see Abuse & takedown.
502 / 503`upstream trouble`	The billing backend or drop index is briefly unreachable. Retry shortly — deploys themselves fail open where safe.

Browsers vs. API clients

On served drops (*.hurled.page), requests with Accept: text/html get small branded error pages for not-found, expired and removed drops; everything else gets the JSON envelope. The API origin (hurl.page) always speaks JSON.

Edit this page on GitHub

Last updated Jun 12, 2026