Rate limits

The API enforces two independent limits. A rate limit caps how many requests you can make per minute. A quota caps how many you can make per month. They are reported and enforced separately, and a 429 can come from either.

The rate limit

On the free plan you can make 60 requests per minute. The limit is keyed to your project, resolved from your API key or token, so it is yours alone and not shared with other callers.

Every response carries advisory headers describing where you stand, written as IETF structured fields:

• RateLimit is the current state: requests remaining (r) and seconds until the window resets (t).
• RateLimit-Policy is the policy itself: the allowance (q) and the window in seconds (w).

RateLimit: "rpm";r=59;t=60, "codex.data";r=4317;t=512000
RateLimit-Policy: "rpm";q=60;w=60, "codex.data";q=5000;w=2592000

You do not have to parse these to use the API, but they let you pace yourself without guessing. The practical move is to watch RateLimit's r (remaining): when it runs low, ease off before you hit zero rather than sprinting into a 429 and waiting out the Retry-After.

The quota

The free plan also allows 5,000 data requests per month, shared across all versions (v1, v2, and v3 draw on the same cap). The counter resets at the start of each month.

When you hit a limit

Either limit answers with a 429 and a Retry-After header giving the number of seconds to wait. The two cases are told apart by the code field in the problem+json body:

• rateLimit/exceeded: too many requests this minute. Retry-After is small; wait it out and continue.
• quota/exhausted: the monthly quota is spent. Retry-After counts down to the monthly reset.

{
  "type": "https://docs.floracodex.com/problems/rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rateLimit/exceeded"
}

Honor Retry-After rather than retrying right away. For repeated rateLimit/exceeded responses, back off exponentially. A quota/exhausted will not clear until the monthly reset, so there is no point retrying before then. The Errors guide covers the envelope and which failures are worth a retry.