Skip to content

Rate limits ​

Limits are per key, per minute, and reads and writes have separate budgets. Exhausting one does not affect the other.

Default tierHigh tier
Writes (POST, DELETE)60 / minute300 / minute
Reads (GET)600 / minute3000 / minute

Every key is on the default tier. A key on the high tier is marked as such in Settings → API Keys — if the default is genuinely too low for what you are building, ask rather than working around it.

You never have to guess ​

Every response — successes included — carries the current state of your budget:

http
RateLimit: limit=60, remaining=41, reset=27
RateLimit-Policy: 60;w=60
RateLimit-Limit: 60
RateLimit-Remaining: 41
RateLimit-Reset: 27

reset is seconds until the window rolls over.

Both the current draft-ietf-httpapi-ratelimit-headers names and the older widely-deployed ones are sent, so whichever your HTTP client already understands is there. Read them rather than counting your own calls: your count does not know about retries, other processes sharing the key, or the tier.

The window is fixed ​

The minute is a fixed window, not a rolling one — it resets on the wall clock, not 60 seconds after your first call.

This has one consequence worth knowing

Across a boundary you can land up to twice the limit in quick succession: 60 writes at 12:00:59 and 60 more at 12:01:00 are both allowed. That is fine — it is a fairness control, not a security boundary — but do not design a burst to depend on it.

When you exceed one ​

You get 429 RATE_LIMIT_EXCEEDED with a Retry-After header, in seconds:

json
{
  "type": "about:blank",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "RATE_LIMIT_EXCEEDED",
  "detail": "Quota of 60 write requests per minute exhausted. Retry in 4s."
}

Honour Retry-After rather than backing off on a schedule of your own. Because the window is fixed, the value is exact — waiting longer wastes budget, and retrying sooner just spends another rejection.

Nothing was written, so retrying a 429 is always safe.

Staying inside them ​

Batch rather than loop. One call creating 50 links costs one write; fifty calls cost fifty. That single change is usually the difference between comfortably inside the budget and permanently against it. See Creating links in bulk.

Spread scheduled jobs. A nightly job that fires everything at midnight will hit the ceiling; the same work paced across a few minutes will not.

Use one key per system. Budgets are per key, so a batch job sharing a key with your live integration will starve it.

Zefi API v1