rate_limit_exceeded
A request limit refused the call. scope per_api_key: wait Retry-After. scope monthly: the plan quota is used up; the response names the cheapest plan that covers your usage, its price and checkout link, and credits.
When it fires
A limit refused the request. The scope field says which one, and the two that matter have different fixes:
scope: "per_api_key": more than 600 requests in 60 seconds on one key. WaitRetry-Afterseconds and slow down.scope: "monthly": your plan's monthly request quota is used up (Free includes 1,000 requests a month, Starter 100,000). Waiting means untilresets_at, the start of next month.scope: "daily_ai": the daily AI request quota. Other endpoints keep working.
Response shape
Every Repull error follows the same envelope. The code is stable and safe to switch on.
{
"error": {
"code": "rate_limit_exceeded",
"message": "You have exceeded your monthly request quota for the 'free' tier (1000 / 1000). Quota resets 2026-12-01T00:00:00.000Z.",
"fix": "Upgrade to Starter: $99 a month for your 2 listings with 100,000 requests a month, at https://repull.dev/dashboard/billing?upgrade=starter. Add credits at https://repull.dev/dashboard/billing to keep going right away ($1 per 1,000 requests beyond your plan), or wait 1684800s for the quota to reset at 2026-12-01T00:00:00.000Z.",
"docs_url": "https://repull.dev/docs/errors/rate_limit_exceeded",
"request_id": "req_01J5X7Y8Z9ABCDEF12345678",
"retry_after": 1684800,
"tier": "free",
"scope": "monthly",
"limit": 1000,
"used": 1000,
"resets_at": "2026-12-01T00:00:00.000Z",
"projected_monthly_requests": 2858,
"upgrade": {
"plan": "starter",
"name": "Starter",
"monthly_price_usd": 99,
"listings": 2,
"monthly_requests": 100000,
"daily_requests": 25000,
"checkout_url": "https://repull.dev/dashboard/billing?upgrade=starter",
"contact_email": null
},
"credits": {
"usd_per_1000_requests": 1,
"top_up_url": "https://repull.dev/dashboard/billing",
"balance_usd": null
}
}
}How to fix
- Per-minute (`per_api_key`): wait the `Retry-After` seconds, then retry with exponential backoff and jitter.
- Monthly (`monthly`): the response carries `upgrade`, the cheapest plan that covers your usage, with its exact monthly price for your listings and a `checkout_url` that opens checkout for that price. On Free that is usually Starter: $99 a month with 100,000 requests and 10 listings included.
- Or keep going right away on credits: `credits.usd_per_1000_requests` is the price ($1 per 1,000 requests beyond your plan) and `credits.top_up_url` is where to add them.
- Or cut the volume: webhook deliveries do not count as requests, so a webhook instead of polling usually brings usage down a lot.
Common gotchas
- Do not retry a monthly refusal on a timer.
Retry-Afteron it is the number of seconds until next month. upgrade.monthly_price_usdis exactly what checkout charges: Starter's base plus its per-listing price forupgrade.listings, which counts every listing you have connected, including ones your plan holds back. When no self-serve plan covers your usage (you are already on Starter, you need more than its quotas, or you have more than 100 listings),upgrade.planis"custom"andupgrade.contact_emailis where to ask.- The per-minute refusal carries no
upgradeorcredits: a plan change does not lift it. - Two related codes carry the same
upgradeandcredits: credits_exhausted (402, your credits ran out) and daily_limit_exceeded (the daily cap).
Examples
curl
curl -i https://api.repull.dev/v1/reservations -H "Authorization: Bearer $REPULL_API_KEY"
# HTTP/2 429
# {"error":{"code":"rate_limit_exceeded","scope":"monthly","resets_at":"2026-12-01T00:00:00.000Z",
# "upgrade":{"plan":"starter","monthly_price_usd":99,"checkout_url":"https://repull.dev/dashboard/billing?upgrade=starter",...},
# "credits":{"usd_per_1000_requests":1,...}}}
# Usage and limits at any time (never refused, even over the quota)
curl https://api.repull.dev/v1/usage/tier -H "Authorization: Bearer $REPULL_API_KEY"TypeScript
const res = await fetch('https://api.repull.dev/v1/reservations', {
headers: { Authorization: `Bearer ${process.env.REPULL_API_KEY}` },
})
if (res.status === 429) {
const { error } = await res.json()
if (error.scope === 'per_api_key') {
await new Promise((r) => setTimeout(r, Number(res.headers.get('Retry-After') ?? 1) * 1000))
} else if (error.scope === 'monthly') {
// Waiting means until next month. Show the person the way on:
const { upgrade, credits } = error
if (upgrade.checkout_url) {
console.error(`Monthly quota used up. ${upgrade.name} covers your usage for $${upgrade.monthly_price_usd}/mo: ${upgrade.checkout_url}`)
}
console.error(`Or add credits ($${credits.usd_per_1000_requests} per 1,000 requests): ${credits.top_up_url}`)
}
}If you're an AI agent
Check error.scope. per_api_key: wait Retry-After seconds, then retry with backoff. monthly: the plan's monthly request quota is used up and retrying will not help until resets_at. Tell the human: error.upgrade is the cheapest plan that covers their usage, with its exact monthly price and a checkout_url; error.credits is the pay-as-you-go alternative ($1 per 1,000 requests) at credits.top_up_url.
Related
- Error reference — the full table of error codes
- Using Repull from AI agents — patterns for handling errors in agent loops
- Rate limits
- Credits and usage
- daily_limit_exceeded
Hit an error that isn't covered? Email hello@repull.dev with the request id from the response headers.