Error codes

Every error is a JSON object with one field, error, holding a sentence written to be shown to a person rather than a code to be looked up. This page is that list, with what causes each one.

All errors are JSON · the error field is always present

Branch on the status, show the sentence The status code is the stable part. The wording is not: it is written for humans and may be reworded without a version bump. Put error straight into your interface and nobody has to look anything up.

The list

Status	Message	What it means
400	`invalid json`	The body was not parseable JSON.
400	`url required`	Preview was given nothing to look at.
400	`slug required`	No slug was given.
400	`invalid slug`	The slug was the wrong shape, or a full URL from another host was passed to the reveal endpoint.
400	`slug must be 3-32 chars: a-z 0-9 _ -`	A custom slug was the wrong shape. Checked before storage is touched.
400	`password must be 4-64 characters`	The password was outside that range.
400	`urls array required`	Bulk needs an array of addresses.
400	`max 10 links per request`	Bulk takes ten at a time.
400	`that address will not be fetched`	Preview was pointed at a private or loopback address, or a port that is not an ordinary one. Carries a `reason` of `host`, `private` or `port`.
400	`confirmation required`	A sweep was posted to without the confirmation word.
403	`wrong password`	Unlock was attempted and the password did not match.
404	`no such link`	Nothing live under that slug.
404	`that link has expired`	It existed and its seven days are up.
404	`that link is not protected`	Unlock was attempted on a link with no password.
409	`slug taken`	Someone has that slug, right now. Retrying will not help.
409	`slug reserved`	The site needs that slug for itself. Nobody can have it, ever.
429	`rate limited` or `rate limited, wait a minute`	Too many requests in the current minute, with a `retry-after` header. See the limits page.

Three that are easy to confuse

slug taken vs slug reserved

The first is a collision and the other slug will do. The second is permanent and no amount of retrying will help. Treating them the same means either giving up too early or retrying forever.

no such link vs that link has expired

The first means it never existed. The second means it did, and its seven days are up. Only the second is worth retrying with a different link.

429 vs a slow response

A 429 arrives immediately with a header telling you how long to wait. A slow response is not a 429 and waiting will not change it.

Handling them

400 and 409 are yours to fix. Retrying the identical request gets the identical answer, because nothing about it changed.
404 on a slug you just created is either the wrong host or an expired link. Check with /api/check, which distinguishes the two.
429 always carries retry-after. Use the value in the header rather than assuming sixty seconds.
An empty preview is not an error. A page that could not be reached comes back 200 with empty fields. Only an address we refuse to fetch is a 400.