API Integration documentation

Error codes

What each code means, and what to do about it.

Errors always carry a JSON body. Two shapes coexist:

  • {"message": "…"} — access or resource error;
  • {"error": "machine_code", "message": "…"} — error on the submission path, meant to be handled by the script. The captcha errors carry the error field alone, without a message.

Test the error field when it is present: it is the stable part, unlike the message, which follows the visitor's language.

By HTTP code

Code Meaning What to do
401 Token missing, unknown or expired; wrong credentials Obtain a valid token
403 Access denied: origin, signature, captcha, token from another organization, website disabled Read the error field
404 Unknown website, form, token or department Check the identifier
413 Request body too large Send less — see below
422 Validation Read errors, field by field
429 Too many requests Wait, then retry — see Rate limiting
503 Service temporarily unavailable Retry later

By error field

error Code Cause Expected reaction
origin_not_allowed 403 The page's Origin does not match the website's host Check that the page is served from the declared domain
invalid_signature 403 Signature missing, tampered with or expired Request a new signature, retry once
captcha_required 403 No captcha token received Solve the captcha from the chain
captcha_failed 403 Token rejected by the provider, or longer than 4 096 characters Do not retry: the request is deemed automated
captcha_provider_not_allowed 403 Chain link unknown to the website's chain, or not one this submission may use Use the first link, the one a fallback_token designates, or an ALTCHA link
captcha_fallback 403 Chain link unavailable Resume at the next link, carrying the fallback_token, once per link
altcha_not_enabled 404 The website does not have ALTCHA in its chain Do not request an ALTCHA challenge for this website
payload_too_large 413 Request body over the limit for this endpoint Send less; see below

Request body size

Every /api/… request has a ceiling, checked on the announced Content-Length first, so an oversized body is never even read:

Endpoint Ceiling
POST …/forms/{slug}/submit 256 KB
Every other /api/… endpoint 64 KB

Beyond it, the answer is 413 {"error": "payload_too_large"}, and the request is not written to the API log. A refused submission is lost: an integration that uploads long free-text fields should check its size before sending. On top of that ceiling, a submission keeps at most 50 keys and 10 KB of undeclared fields; declared fields are never trimmed.

Errors that do not exist

No quota error is ever returned to a visitor: a request received beyond the client's plan is recorded normally, only the notification stops.

No 500 is expected on the tracking path: a failure to record a visit is logged server-side and still returns a 200, so that a page is never broken.