Repull
DocumentationChannelsStudioMigrateAPI ReferenceBuild with AIKnowledge BaseWebhooks
Docs/Documentation/Errors

credits_exhausted

Past the plan's monthly quota and the Repull credits that pay for usage beyond it have run out (or are paused). Top up to resume.

HTTP 402The workspace is over a plan cap. Trim usage or upgrade.

When it fires

You are past your plan's monthly request quota, and the Repull credits that pay for usage beyond it have run out, or are paused because an auto-recharge payment failed.

Requests within your quota are not affected; only requests beyond it are refused until there is credit again. Nothing about your data, listings or connections changes.

Response shape

Every Repull error follows the same envelope. The code is stable and safe to switch on.

{
  "error": {
    "code": "credits_exhausted",
    "message": "<human-readable explanation of what went wrong>",
    "docs_url": "https://repull.dev/docs/errors/credits_exhausted"
  }
}

How to fix

  1. Top up at https://repull.dev/dashboard/billing. Requests resume within a minute of the payment.
  2. Turn on auto-recharge on the same page so your integration never stops at a zero balance.
  3. If credits are paused after a failed recharge, update your card when you top up; the pause lifts with any successful payment.
  4. If you regularly use close to 100,000 requests a month, Starter includes them for $99 and costs less than credits.

Common gotchas

  • Waiting does not help. Unlike rate_limit_exceeded, this is a 402: there is no Retry-After, and retrying on a timer returns the same answer until you top up.
  • The error body includes balance, limit and used so you can show the state in your own tooling. GET /v1/usage/summary returns the same in its credits object at any time.
  • See Credits and usage for how credits are charged.

Examples

curl

# Past the monthly quota with an empty wallet
curl -i https://api.repull.dev/v1/reservations \
  -H "Authorization: Bearer $REPULL_API_KEY"
# HTTP/2 402
# {"error":{"code":"credits_exhausted","balance":0,"limit":1000,"used":1840,...}}

# Check the wallet at any time
curl https://api.repull.dev/v1/usage/summary \
  -H "Authorization: Bearer $REPULL_API_KEY"
# { "credits": { "balanceUsd": 0, "active": false, "requestsCovered": 0, ... } }

TypeScript

const res = await fetch('https://api.repull.dev/v1/reservations', {
  headers: { Authorization: `Bearer ${process.env.REPULL_API_KEY}` },
})
if (res.status === 402) {
  const { error } = await res.json()
  if (error.code === 'credits_exhausted') {
    // Retrying will not help — this needs a top-up (or auto-recharge).
    console.error(`Repull credits exhausted (${error.used}/${error.limit} this month). Top up at https://repull.dev/dashboard/billing`)
    return
  }
}

// Watch the balance before it runs out: requests served on credits say so.
if (res.headers.get('X-Repull-Billing') === 'credits') {
  const balance = Number(res.headers.get('X-Repull-Credit-Balance'))
  if (balance < 5) console.warn(`Repull credits low: $${balance}`)
}

If you're an AI agent

The workspace is past its plan's monthly request quota and its pay-as-you-go Repull credits are empty or paused. Do NOT retry on a timer — there is no Retry-After and the answer will not change. Tell the human to top up (or enable auto-recharge) at https://repull.dev/dashboard/billing; requests resume within a minute of the payment. Requests within the quota are unaffected.

Related

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

Previous← daily_limit_exceededNextlistings_limit_exceeded →
AI