Errors
Errors use standard HTTP status codes and a JSON body that says what went wrong.
The error body
Errors follow the Problem Details format (RFC 7807). The status code tells you the category; detail tells you what happened, in English:
{ "type": "/errors/404", "title": "An error occurred", "status": 404, "detail": "Not Found"}Some business errors use a shorter form, with an optional context holding structured details:
{ "title": "Invalid Request", "status": 400, "detail": "Missing organization filter. Provide either \"organization.id\" or \"organization.slug\"."}Validation errors
When a request body breaks a rule, the API answers 422 Unprocessable Entity with one entry per problem in violations. propertyPath names the field:
{ "status": 422, "detail": "email: This value is not a valid email address.", "violations": [ { "propertyPath": "email", "message": "This value is not a valid email address.", "code": "bd79c0ab-…" } ]}Show message next to the field it concerns; it is written for people.
Status codes
| Code | Meaning | What to do |
|---|---|---|
200, 201, 204 | Success | |
304 | Not modified | Reuse your cached copy |
400 | The request is malformed or not allowed in this state (slot taken, registrations closed, missing filter) | Read detail; do not retry unchanged |
401 | No valid credentials | Check the API key |
403 | Authenticated, but not allowed, or the module is not enabled for this organization | Check the role of the key's owner and the organization's modules |
404 | Unknown organization, slug or identifier, or unpublished content | Check the identifiers and the publication status |
422 | Validation failed | Fix the fields listed in violations |
429 | Too many requests | Wait, then retry; see Rate limiting |
5xx | Something went wrong on our side | Retry with backoff; contact us if it persists |
Retrying safely
Retry 429 and 5xx responses with exponential backoff. Do not retry 4xx responses other than 429 unchanged: they will fail again. Creating requests (POST) are not idempotent, so before retrying a reservation or a registration after a timeout, check whether the first attempt went through.