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.

HTTP 429You have hit a rate limit.

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. Wait Retry-After seconds 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 until resets_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

  1. Per-minute (`per_api_key`): wait the `Retry-After` seconds, then retry with exponential backoff and jitter.
  2. 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.
  3. 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.
  4. 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-After on 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 for upgrade.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.plan is "custom" and upgrade.contact_email is where to ask.
  • The per-minute refusal carries no upgrade or credits: a plan change does not lift it.
  • Two related codes carry the same upgrade and credits: 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.

Hit an error that isn't covered? Email hello@repull.dev with the request id from the response headers.

AI