Developers
Rate limits
Limits are counted per key or connection, not per account, so one busy integration cannot slow down another. Go over and the API answers 429 with Retry-After.
The limits
| What | Limit | Counted per |
|---|---|---|
Reviews API (/api/v1) | 120 requests a minute | Secret key or OAuth connection |
Adding reviews (POST /v1/companies/{company}/reviews) | 60 a minute and 1,000 a day, on top of the above | Secret key or OAuth connection |
Public reviews API (/v1/public/*) | 600 requests a minute | Publishable key |
Review feeds (/feeds/{key}/...) | 120 requests a minute | Publishable key |
OAuth token and revoke (/mcp/oauth/token, /revoke) | 120 a minute | IP address and client |
OAuth sign-in (/mcp/oauth/authorize) | 60 a minute | IP address |
OAuth client registration (/mcp/oauth/register) | 30 an hour | IP address |
| Reviews MCP tool calls | 240 every 10 minutes per connection, and 960 per user across all of their connections | API key or connected AI app, and user |
Answers served from a conditional request (304 Not Modified) still count. AI reply drafts also have a monthly ceiling; reaching it answers 429 without Retry-After until the next month.
Headers
| Header | Sent on | Meaning |
|---|---|---|
X-RateLimit-Limit | Reviews API and public reviews API answers | Requests allowed in the current minute |
X-RateLimit-Remaining | Reviews API and public reviews API answers | Requests left in the current minute |
Retry-After | Every rate-limit 429 (except the monthly AI draft ceiling) | Seconds to wait before the next try |
X-RateLimit-Reset | Reviews API 429 answers | When the window resets, as Unix seconds (not readable from browser JavaScript; use Retry-After) |
429 Too Many Requests
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 17
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1795075217
{
"type": "about:blank",
"title": "Too Many Requests",
"status": 429,
"detail": "Too many requests from this API key or app connection. Try again in 17 seconds."
}
Back off and retry
On 429, wait the Retry-After seconds and try again. On 500, 502 and 503, retry with an exponential backoff (1, 2, 4, 8 seconds...). Give up after a few tries and log the X-Request-Id.
Retry after 429 and 5xx
# curl 7.66 or later waits for Retry-After before each retry curl --retry 5 https://app.grades.com/api/v1/companies \ -H "Authorization: Bearer $GRADES_API_KEY"
Retry after 429 and 5xx
async function gradesFetch(url, options = {}, attempts = 5) {
for (let i = 1; ; i += 1) {
const res = await fetch(url, { ...options, headers: { ...headers, ...options.headers } });
const retryable = res.status === 429 || res.status >= 500;
if (!retryable || i === attempts) return res;
const wait = Number(res.headers.get('Retry-After')) || Math.min(60, 2 ** i);
await new Promise((resolve) => setTimeout(resolve, wait * 1000));
}
}
const res = await gradesFetch(`${API}/companies`);Retry after 429 and 5xx
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
session = requests.Session()
session.headers.update(headers)
# Retries 429 and 5xx; honors Retry-After, otherwise backs off 1 s, 2 s, 4 s...
retry = Retry(total=5, backoff_factor=1, status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=None, respect_retry_after_header=True)
session.mount("https://", HTTPAdapter(max_retries=retry))
r = session.get(f"{API}/companies", timeout=30)Retry after 429 and 5xx
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;
use Psr\Http\Message\ResponseInterface;
// Retries 429 and 5xx up to 5 times; waits Retry-After seconds, otherwise 2, 4, 8... (at most 60)
$stack = HandlerStack::create();
$stack->push(Middleware::retry(
fn (int $retries, $request, ?ResponseInterface $response = null) =>
$retries < 5 && $response && ($response->getStatusCode() === 429 || $response->getStatusCode() >= 500),
fn (int $retries, ?ResponseInterface $response = null) =>
1000 * ((int) $response?->getHeaderLine('Retry-After') ?: min(60, 2 ** $retries)),
));
$grades = new GuzzleHttp\Client([
'base_uri' => 'https://app.grades.com/api/v1/',
'handler' => $stack,
'http_errors' => false,
'headers' => ['Authorization' => 'Bearer ' . getenv('GRADES_API_KEY'), 'Accept' => 'application/json'],
]);
$res = $grades->get('companies');- Spread bulk work: 120 a minute is two requests a second. Use
limit=100on lists instead of many small pages. - Prefer webhooks to polling for new reviews; send
If-None-Matchwhen you do poll. - Contact us if your integration needs a higher limit.