Rate limits

Each API key may make 120 requests per minute against /v1. The limit is per key, not per account or per IP, so separate keys for separate services do not compete.

Headers

Header	When	Meaning
X-RateLimit-Limit	Every response	The per-minute limit, 120.
X-RateLimit-Remaining	When the limiter answered	Requests left in the current window.
X-RateLimit-Reset	When the limiter answered	When the window resets, as Unix seconds.
X-RateLimit-Degraded	Only when the limiter was unavailable	true. The request was admitted without being counted.
Retry-After	429 only	Whole seconds to wait, at least 1.

Remaining and Reset are real numbers about a real bucket. When the limiter cannot be reached they are left out instead of invented, and X-RateLimit-Degraded: true is sent. The limiter fails open: an outage in it does not stop your requests.

When you are over

The request is refused with 429 and rate-limited. Wait Retry-After seconds and send it again. The SDK does this for you, and so does the CLI through the SDK.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1788344100
Retry-After: 12

Staying under it

• Poll a conversion every few seconds, not in a tight loop. The SDK's wait() polls every 3 seconds by default.
• Prefer webhooks to polling when you run many conversions.
• Cache GET /v1/presets. It is cacheable for five minutes.
• Read X-RateLimit-Remaining and slow down before it reaches zero. The SDK exposes the last values as esfera.rateLimit.