Skip to main content
Running out of credits mid-batch is disruptive, especially if your system doesn’t notice until the error rate spikes. Catch it early, degrade gracefully, and route around it.

Early detection

Poll your credit balance before starting work that will consume a lot:
This isn’t foolproof (other requests on the same workspace can consume credits between your check and your actual /v1/read call), but for big batches it catches the obvious “you’re nowhere near enough” case.

Catching the 402

When /v1/read returns insufficient_credits:

Low-credit webhook

Subscribe to credit.low to get notified before you run out:
Reader fires this event when your balance drops below 10% of your monthly limit. That gives you runway to:
  • Alert an operator
  • Pause background workers
  • Switch to a higher tier automatically (if you have a billing API)
  • Queue further requests until the next reset

Graceful degradation strategies

When you’re out of credits, what should your app actually do?
  • Cached responses only. Set cache: true (the default) and accept that anything not already cached is unavailable until reset. Cache hits are free.
  • Queue and defer. Accept user requests, queue the scrapes, run them when credits come back.
  • Fail visibly to users. Better than silent corruption; show a “service degraded” banner.
  • Switch to a cheaper mode. Temporarily force proxyMode: "standard" instead of premium to cut the cost by up to 3x per page.

Credit budget per worker

For sustained workloads, budget your credits like you budget memory: cap each worker’s daily draw and alert when it exceeds.

Next