Rate Limits & Errors

Rate limits

Requests are rate-limited per API key. The default allowance is:

60 requests per minute, with short bursts allowed.

This is generous for syndication: most sites fetch your listings once per page load (or once per build), not per visitor. If you render from the browser on a busy site, proxy or cache the response on your own server rather than calling the API on every visit — see CORS & Embedding → Where to put the key.

Every response includes rate-limit headers so you can stay under the cap:

Header	Meaning
`X-RateLimit-Limit`	Your per-minute request ceiling
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	Unix epoch seconds when the window resets

When you exceed the limit you get 429 Too Many Requests with a Retry-After header (seconds to wait). Back off until then and retry.

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1781000460

Need a higher limit for a large portfolio or a high-traffic site? Ask via your Commercial Units account contact.

Errors

All errors return a JSON body of the shape:

{ "error": "short_machine_code", "message": "Human-readable explanation." }

Status	`error`	When it happens	What to do
`400 Bad Request`	`bad_request`	Malformed query param (e.g. non-numeric `page`)	Fix the request
`401 Unauthorized`	`unauthorized`	Missing / malformed / revoked / unknown API key	Check the `Authorization: Bearer <key>` header; the key may have been revoked — create a new one
`403 Forbidden`	`origin_not_allowed`	Valid key, but the browser request's `Origin` isn't on your allow-list	Add your site's origin in Settings → Developer (CORS)
`404 Not Found`	`not_found`	Listing id doesn't exist, isn't active, or isn't yours	Use an id from `GET /v1/listings`; expired/leased listings drop out
`429 Too Many Requests`	`rate_limited`	You hit the per-key rate limit	Honour `Retry-After`, then retry; cache/proxy to reduce calls
`500 Internal Server Error`	`internal_error`	Something failed on our side	Retry with backoff; if it persists, contact support

401 vs 403 — a quick rule

401 = "we don't trust this key." (missing/wrong/revoked key)
403 = "the key is fine, but we don't allow this origin." (CORS allow-list)

If a browser fetch fails but the same key works from curl, it's almost always a 403 origin problem — register your site's origin.

Handling errors well

Treat 429 and 5xx as retryable with exponential backoff; treat 400, 401, 403, 404 as non-retryable (fix the request/config first).
Read X-RateLimit-Remaining and slow down before you hit 0.
Log the error code and message — they're stable, machine-readable, and tell you exactly which doc page to check.