Errors and redirects¶

When letterpost rejects a submission, where the visitor ends up depends on how the form was sent.

Browser forms¶

A normal HTML form gets a redirect:

With a redirect URL in the form's settings and a _redirect_error field, the browser goes to that path with the error code added, for example https://example.org/contact?error=captcha_failed. Your page can read the code and show a message.
Otherwise the browser lands on letterpost's error page, which explains the code in plain words.

Some errors happen before letterpost has read the submission, so they always go to letterpost's error page, even with _redirect_error: not_found, too_large, and invalid for a body that can't be read.

After a successful submission, the browser goes to _redirect (or the redirect URL itself), or else to letterpost's thank-you page. See Form fields.

JSON requests¶

A request sent as JSON, or with Accept: application/json, gets no redirect. It gets the HTTP status and a JSON body with an error member. That is a message, or, when the submission fails validation (status 422), an object with one message per field (form for problems with the submission as a whole):

{"error": {"email": "must be a valid email address"}}

See JSON submissions.

Error codes¶

Code	HTTP status	Meaning
`not_found`	404	There is no form with this ID. Check the endpoint.
`invalid`	400, 415 or 422	The submission is not valid: the `email` field is missing or wrong, there are no fields or more than 25, `_subject` is too long, `_redirect` is used without a redirect URL, the honeypot field is missing, or the body could not be read.
`too_large`	413	The request is larger than 128 KB.
`origin_not_allowed`	403	The website is not in the form's list of allowed websites.
`form_inactive`	403	The form is switched off in its settings.
`captcha_missing`	400	The form has a captcha, but the submission has no captcha answer.
`captcha_failed`	403	The captcha answer was wrong, expired or already used.
`captcha_unavailable`	503	The captcha could not be checked right now. Try again.
`quota_exceeded`	429	The form's account has received far more submissions this month than its plan allows. See Plans and limits.
`server_error`	500	Something went wrong at letterpost. Try again later.

Sending more than a few requests per second from the same address is answered with status 429 and the JSON message "rate limit exceeded", also for browser forms.