Rate limits

The OLET API limits how many requests you can make in a given window. Stay under the limits below and you will never see one; go over, and you get a 429 you should back off from rather than retry immediately.

What happens when I hit a limit

You get a 429 response in the usual error envelope:

{ "error": { "code": "RATE_LIMITED", "message": "Too many requests. Try again later." } }

curl -i https://api.oletapp.com/your-store/v1/products \
  -H "Authorization: Bearer olet_live_YOUR_API_KEY"

const res = await fetch(url, { headers })
if (res.status === 429) {
  const retryAfter = Number(res.headers.get('retry-after')) // seconds
  // wait that long, then retry
}

A 429 carries a Retry-After header with the number of seconds to wait. Every response also carries RateLimit-Policy (the limit and its window) and RateLimit (for example limit=120, remaining=118, reset=42, where reset is the seconds left in the window). Read those rather than guessing a wait time, and use an exponential backoff if you are retrying automatically.

What are the limits

General use:

• 120 requests per minute, per credential. This is the main limit almost every call counts against.
• 30 requests per minute, per credential, specifically for customer endpoints. This is a separate, smaller budget on top of the general one, so heavy customer lookups do not eat into your budget for everything else.
• 10 requests per minute, per credential, specifically for a product write that includes an image_url to download. A product write with no image does not count against this one. Separately, only a few image downloads run at the same time across the whole API, so a busy moment can answer 429 RATE_LIMITED (“Too many image imports in progress. Try again shortly.”) with nothing written. Retry shortly.

Failed authentication:

• 30 failed requests per 5 minutes, counted per combination of the caller’s network address and the credential presented. A request fails here when it answers 401, 402 or 403. Successful requests never count against this.
• 300 failed authentication attempts per 5 minutes, counted per network address alone, as a broader backstop. This is sized generously because some integration platforms share network addresses across many customers.

Token endpoint:

• 30 failed requests per 5 minutes per network address on POST /oauth/token. A normal refresh loop never counts against it. This one answers in the OAuth error shape, {"error": "invalid_request", "error_description": "Too many requests. Try again later."}, not the usual envelope.

How should I handle a 429

Slow down and retry after the window indicated in the response headers, not immediately. If you are polling on a schedule, widen the interval rather than retrying in a tight loop. If you are seeing failed-authentication limits specifically, double check the credential you are sending before retrying at all, since retrying a bad credential repeatedly only delays you further.

Where to go next

See errors for every other error code, or the full API reference for per-endpoint details.