Rate Limits

The WedStay API uses rate limits to ensure fair usage and platform stability.

Tiers

Every window rolls: the burst limit counts the last 60 seconds and the daily limits count the last 24 hours. The venue detail limit keeps the full catalog from being copied one venue at a time and is counted separately from the daily read limit.

List endpoints return at most 100 results per page (limit, default 20). The keyless MCP server's search_venues tool returns at most 50 per call.

Rate limit headers

Every API response carries rate limit headers:

A request sent without an API key, such as GET /api/v1/openapi.json or a 401 for a missing key, is answered by the per IP limit that protects the whole site: 400 requests per minute per IP address, so X-RateLimit-Limit is 400 (and the reset is also in Unix seconds). A 401 for an invalid or revoked key carries no rate limit headers: the key is checked before any limit is counted.

Example headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1790000060

429 Response

When you exceed a rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please slow down.",
    "request_id": "req_abc123",
    "doc_url": "https://www.thewedstay.com/developers/errors#rate_limit_exceeded",
    "hint": "Per-minute burst limit hit. Wait until X-RateLimit-Reset (Unix seconds) and retry with backoff."
  }
}

The venue detail and inquiry limits answer with their own codes, venue_detail_rate_limit_exceeded and inquiry_rate_limit_exceeded. See Errors.

Best practices

1. Cache responses. Venue data changes infrequently. Cache search results for at least 5 minutes.
2. Use pagination. Don't fetch all venues at once. Use the cursor and limit parameters.
3. Check headers. Monitor X-RateLimit-Remaining to avoid hitting limits.
4. Implement backoff. On 429 responses, wait for the Retry-After duration before retrying.
5. Batch where possible. Use search filters to get the data you need in fewer requests.