Rate Limits

How the WinWinKit API throttles excessive traffic and how to react when you hit a limit.

Calls to our REST API are rate limited to provide equitable access for everyone and to prevent abuse. We are going to keep evolving these limits as we gather more information, and encourage your feedback.

Limits

Client-facing API requests are limited per project, based on your plan, over a rolling one-minute window. The limit is shared across all of your app’s end users.

Plan	Requests per minute
Free	120
Starter	600
Essential	1,200
Scale	2,400

Traffic is additionally subject to a per-IP safeguard that protects against short bursts and abuse:

Interval	Requests per minute
1 second	30
10 seconds	90
1 minute	300

Requests made with a Secret API Key are server-to-server and governed solely by per-project plan limit — no per-IP limits apply.

Response headers

WinWinKit API follows the IETF RateLimit header fields for HTTP standard. Every response to a client-facing request advertises the current limit via its RateLimit-Policy and RateLimit fields, and a rate-limited (429) response additionally includes a Retry-After field:

RateLimit-Policy: "project-plan";q=600;w=60
RateLimit: "project-plan";r=587;t=42
Retry-After: 42

Header Name	Description
`RateLimit-Policy`	`q` is your plan’s quota and `w` is the window in seconds.
`RateLimit`	`r` is the requests remaining in the current window (`0` once you’re rate limited) and `t` is the seconds until it resets.
`Retry-After`	Seconds to wait before retrying. Sent only on a `429 Too Many Requests` response.

These are standard structured-field headers — any client library that understands the RateLimit specification can consume them directly. Prefer reading these headers over hard-coding the limits, since we evolve them over time.

Handling rate limit errors

Once you exceed the limit, the WinWinKit API returns a 429 Too Many Requests response. It carries the rate-limit headers described above — with RateLimit reporting r=0 and a Retry-After field — alongside the standard error body:

{
  "errors": [
    {
      "code": "TOO_MANY_REQUESTS",
      "status": 429,
      "message": "Too Many Requests",
      "source": null
    }
  ]
}

Honor Retry-After and retry after a short backoff. If you consistently hit the limit during normal usage, batch where you can and avoid tight polling — most user state can be read once and cached client-side.