Errors and limits
Errors
Section titled “Errors”Errors are RFC 9457 application/problem+json:
{ "type": "about:blank", "title": "Not Found", "status": 404, "detail": "no such route"}detail is present only where the message is safe to surface. Backend messages are never passed through.
| Status | Meaning |
|---|---|
| 400 | Request validation failed, or a refused write with a safe message |
| 401 | Missing or invalid bearer token; carries WWW-Authenticate |
| 402 | Plan or quota refused the call |
| 403 | The api_user role may not perform this operation |
| 404 | No such route or resource |
| 409 | Conflicting state, reported by an upstream action |
| 413 | Request body over the limit |
| 422 | Unprocessable content, reported by an upstream action |
| 500 | An unexpected error inside the API |
| 502 | The backend failed in a way the contract does not cover |
| 503 | The authentication service is unreachable; retry later |
Every response carries an x-request-id header. Quote it when reporting a problem.
Pagination
Section titled “Pagination”List endpoints take limit (1 to 100) and offset (default 0). The default limit is 50 for workspaces, brands and labels, and 20 for marketing QR codes and the catalogues.
Brands, labels and marketing QR codes report a total:
{ "items": [], "limit": 50, "offset": 0, "total": 137 }Workspaces and the reference catalogues report has_more instead:
{ "items": [], "limit": 50, "offset": 0, "has_more": true }has_more: true means at least one further item exists. Fetch the next page with offset increased by limit.
Request body limit
Section titled “Request body limit”Request bodies are bounded at 256 KB. A larger body is refused with 413.
Rate limits
Section titled “Rate limits”The API applies no per-caller rate limit itself. Requests may be rate limited per client IP at the CDN edge; on a refusal, back off and retry.