Rate limiting is what stops a single misbehaving client from overloading a public API. It also protects your own quota when you are the misbehaving client (a runaway script, a typo in a loop). GoRest applies a per-token budget that is large enough not to bother developers but tight enough to stop abuse. This guide explains how the budget works, how to read the headers the server sends back, and how to write a client that stays inside the limit.
The budget
Every access token has a default budget of 300 requests per minute. The budget refills smoothly: every second you get back one sixtieth of your limit (5 requests a second at the default), up to the full limit. So a burst can use the whole budget at once, and after that requests come back a few at a time. A call with no token is limited too: 120 calls a minute per IP address.
You can raise or lower the limit per token in /my/tokens (allowed range: 1 to 600 requests per minute). A higher limit is useful for batch jobs that really need to read many resources; a lower limit is useful for test tokens where you do not want to waste budget.
Headers on every response
Every response includes two rate-limit headers (the IETF RateLimit draft format), so your client can stay informed without trial and error:
RateLimit-Policy: "token";q=300;w=60
RateLimit: "token";r=150;t=30RateLimit-Policyis the budget:qcalls in a window ofwseconds. With no token the name is"ip"andqis 120.- In
RateLimit,ris how many calls you can still make, andtis the number of seconds until your budget is full again.
The older X-RateLimit-* headers are not sent in v3. A polite client checks r on each response and slows itself down before hitting zero. A naive client just keeps sending requests and reads 429s. Both work; the first is friendlier and handles short bursts better.
What 429 looks like
When you exceed the budget, the API returns 429 with the same headers, a Retry-After header and a Problem Details body:
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Policy: "token";q=300;w=60
RateLimit: "token";r=0;t=60
Retry-After: 1
{
"type": "https://www.gorest.co.in/docs/api/errors#rate_limited",
"title": "Too Many Requests",
"status": 429,
"code": "rate_limited"
}Back off rather than retrying at once; a retry before the budget refills only gets another 429.
Simple back-off
The simple retry: read Retry-After, sleep that long, retry. This works because the server is telling you exactly when it will let you back in.
async function fetchWithRetry(url, opts = {}, attempts = 3) {
for (let i = 0; i < attempts; i++) {
const res = await fetch(url, opts);
if (res.status !== 429) return res;
const wait = (parseInt(res.headers.get("retry-after"), 10) || 1) * 1000;
await new Promise(r => setTimeout(r, wait));
}
throw new Error("Rate limited; gave up");
}Three attempts are usually enough. If you need more, the upstream is really overloaded, and you have a different problem.
Exponential back-off (when you do not have a hint)
If you are calling an API that does not return a Retry-After header (or a 5xx response that does not), use exponential back-off with jitter. The pattern: each retry waits at least twice as long as the previous one, plus a small random delay so many clients do not all retry at the same time.
import random, time
def with_backoff(fn, attempts=4, base=0.5, cap=10):
for i in range(attempts):
try:
return fn()
except RetryableError:
if i == attempts - 1:
raise
sleep = min(cap, base * (2 ** i)) + random.random() * 0.25
time.sleep(sleep)The "+ random.random() * 0.25" is the jitter. Without it, a thousand clients that all started a job at the same moment would all retry at the same moment, hitting the server together. Jitter spreads them out.
Concurrency vs throughput
Two clients each doing 300 requests per minute is 600 requests per minute total. That is fine if they have different tokens; the budget is per token, not per IP (a call with no token is counted per IP). If you need more throughput from one logical job, the right move is to create a second token rather than open concurrent connections on one token.
Inside one token, raising concurrency does not raise throughput; the server counts each request, not each connection. Two parallel calls on the same token still count as two against the budget.
What to do when you keep hitting the limit
If your application keeps hitting the limit, the question is not "how do I retry harder" but "do I need every one of these calls?" Common fixes that are cheaper than more budget:
- Cache by id. If the same id is read 100 times, fetch it once and remember it for a few seconds. The shape of the data does not change inside a window.
- Batch with filters. Use
filter[email]=/filter[status]=(orsearch=) to pull a filtered list rather than fetching ids one at a time. - Page in larger chunks. The default page size is 25. Larger pages return more data per request, so pass
page[size]=N(up to 100) on any list endpoint to fetch more rows in one call. - Push, do not poll. If you find yourself polling
GET /usersevery 10 seconds to look for changes, use the change stream,/public/v3/stream/changes(Server-Sent Events), instead. Polling that often will use up the budget no matter how big it is.
Test your retry path without waiting
The /public/v3/http/status/429 endpoint returns a 429 (with Retry-After, as a real one does) without using up your real budget. Point your tests at it so you can check the back-off behaviour quickly:
curl -sSi "https://gorest.co.in/public/v3/http/status/429"The body is Problem Details with the code requested_status, so you can tell a test answer from a real rate_limited one. Use /public/v3/http/delay/N to test slow responses as well. The old v2 API works differently (X-RateLimit-* headers and ?force_status=); see /docs/v2.