Rate Limits

Every API key has its own per-endpoint request budget. Budgets are enforced independently per endpoint: exhausting the upload_media budget does not impair your ability to call read_listings_list, and vice versa.

Default per-endpoint budgets

Source: dashboard/fastapi_backend/app/integrations/rate_limit/defaults.py.

Endpoint name	Budget (req/window)	Window
cancel_listing	100 / 60s	60s
create_listing	200 / 60s	60s
get_availability	600 / 60s	60s
get_listing_orders	300 / 60s	60s
get_webhook_catalog	60 / 60s	60s
read_listing_single	600 / 60s	60s
read_listings_list	300 / 60s	60s
read_user_single	600 / 60s	60s
read_users_list	300 / 60s	60s
update_listing_status	200 / 60s	60s
update_section	200 / 60s	60s
upload_media	20 / 60s	60s

Every bucket is sliding-window based on a Redis token bucket keyed on api_key:{api_key_id}:{endpoint_name}.

Response headers

Every response from a rate-limited endpoint carries three headers, on both 2xx and 429 replies:

Header	Meaning
X-Rate-Limit-Limit	Max requests permitted in the current window.
X-Rate-Limit-Remaining	Requests still available before the next 429.
X-Rate-Limit-Reset	Unix epoch seconds when the window next refills.

On a 429 reply the response also carries Retry-After in seconds.

Exceeded budget

A request that would push X-Rate-Limit-Remaining below zero is short-circuited with:

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-Rate-Limit-Limit: 20
X-Rate-Limit-Remaining: 0
X-Rate-Limit-Reset: 1745339418
Content-Type: application/json

{
  "error": {
    "code": "rate_limit.exceeded",
    "message": "Per-key request budget exhausted for the current window.",
    "request_id": "req_01HX5Y7Z2M3N4P5Q6R7S8T9U0V",
    "details": {}
  }
}

Integrators SHOULD honor Retry-After with exponential jitter. A recommended retry schedule is delay = Retry-After + random(0, 5).

Per-key overrides

Need more headroom on a specific endpoint? The platform supports per-key overrides on APIKey.rate_limit_overrides. Contact support@valara.cloud with your key id, the endpoint name, and the steady-state QPS you expect; the support team raises the override through PATCH /api/v1/admin/api-keys/{key_id}/rate-limits (admin only).

Source of truth

The canonical registry lives in dashboard/fastapi_backend/app/integrations/rate_limit/defaults.py. This page is auto-generated from that registry - do NOT hand-edit. The CI drift-guard at .github/workflows/docs.yml blocks PRs whose generated output does not match disk.