Errors and limits

Bodies

Most errors are JSON with one error string. Guest errors, such as a phone number we can’t read, are written for the guest to read.

{ "error": "no such session" }

When a body or query fails validation (a missing field, a wrong type, a value out of range), the error is an object instead. Its message is a JSON string listing each problem and where it is:

{
  "success": false,
  "error": {
    "name": "ZodError",
    "message": "[{\"code\":\"too_small\",\"path\":[\"photos\"],\"message\":\"Too small: expected array to have >=1 items\"}]"
  }
}

A missing or wrong API key is the one plain text body: Unauthorized.

Statuses

Status	Means	What to do
400	A bad body, query or value, or a malformed Authorization header.	Fix the request. Sending it again won’t help.
401	A missing or wrong API key, or one since replaced or revoked.	Check the key. Ask us if it stopped working.
404	No such set or session.	Check the id. Read the queue again.
409	The session is already completed or canceled, or the event isn’t running.	Read the queue or the event list again and move on.
422	Some photo keys aren’t in storage. missing lists them; nothing was saved.	Upload those again and repeat the call.
429	Over a rate limit.	Wait a minute. There is no Retry-After header.
500	Our fault.	Retry after a few seconds, then tell us.

Uploads go to storage, not to this API, so their errors look different: XML in Amazon S3’s format. A 403 there almost always means the Content-Type header doesn’t match the one the URL was signed for.

Rate limits

Creating a session (POST /sets/:setId/sessions) is limited to 60 a minute from one IP address, counted by each Cloudflare data center rather than globally. Nothing else on the booth API is limited; your key is the control.

{ "error": "Too many requests. Try again in a minute." }