API
Errors & quotas
JSON error shape, HTTP statuses, RPM and monthly Redis limits, category and format 403s.
All errors use:
{ "error": "unauthorized", "message": "Missing x-api-key header" }Unexpected failures use { "error": "internal", "message": "Unexpected error" } with status 500.
Status codes
| Status | error | Typical cause |
|---|---|---|
| 400 | bad_request | Invalid color or format |
| 401 | unauthorized | Missing or invalid x-api-key |
| 403 | forbidden | No active contract; category not on the contract; format not allowed; a member of the organization is banned |
| 404 | not_found | Unknown path, make, model, year, variant, or unpublished view |
| 429 | rate_limited | Requests per minute exceeded |
| 429 | quota_exceeded | Monthly request quota exceeded |
| 500 | internal | Unexpected server error |
Quotas
Limits come from the organization contract (see GET /v1/me and the dashboard Contract page).
- RPM — per API key, sliding calendar minute. Exceeding it returns
429rate_limited. - Monthly — per organization, UTC calendar month. Exceeding it returns
429quota_exceededand the extra request is not counted.
Every authenticated /v1 call (including /v1/me, catalog, search, and image JSON) consumes both counters. Fetching the signed image_url is a separate image request and is not billed as a /v1 call.
Contract 403s
- Vehicle category not included →
Contract does not include this vehicle category - Format not in
allowed_formats→Format {format} is not included in this contract - Contract missing or not
active→No active contract for this key - A member of the organization is banned →
Organization access is disabled(all of that org's API keys fail immediately; the request is not billed)