HTTP Status Codes and Errors

HTTP Status Codes

The UploadBooth API returns these HTTP status codes:

200 OK: Success — and most API failures. JSON error responses are delivered with status 200; always check the type field of the response envelope, not just the status code.
302 Found: Redirect, e.g. from api/download to the canonical .zip URL or to a batch password page.
304 Not Modified: Conditional GET against previously cached content.
400 Bad Request: Invalid input on media endpoints, e.g. an invalid preview size or a corrupt archive.
404 Not Found: The resource requested — user, batch, or file — does not exist (preview and password flows).
500 Internal Server Error: Unhandled server-side errors return an HTML error page; some are triggered by ordinary client mistakes (e.g. invalid sorting on api/order).
502 Bad Gateway: UploadBooth is down or being upgraded; also returned when the image preview service is unavailable.

Authentication failures do not produce 401: authorized methods reply with a 200 JSON error instead.

When the UploadBooth API returns error messages, it responds in JSON, using the standard envelope:

{"result":"<human-readable explanation>","type":"error"}

Common error results:

Authorize first. — authorized method called without valid credentials.
Unknown user / Batch not found. — nonexistent login or batch.
Invalid login or password — api/authenticate failure.
Password is incorrect. / Batch has no password. — api/check_batch_password failures.

Note: api/rename error results are raw, untranslated message keys such as batch_name_taken.