Understand credits and retries

Reserve, settle and release

Luni reserves the maximum expected cost before work begins. Successful work settles the relevant credits, while unused reservations are released. The workspace distinguishes available credits, consumed credits and credits currently held for work in progress.

The beta schedule is one credit for a successful scrape or map, two for a completed search, one for each successfully fetched search page, one per successful crawl page and 40 per successful company profile. A Studio preview costs one credit, as does each useful page in a saved scraper run, and a successful monitor check costs one. Company research is available only to invited enterprise customers.

Persist the idempotency key before sending

Create a logical request ID when a work item is created, store it with the request body and send it as Idempotency-Key. If a process crashes or the HTTP connection is interrupted, the next worker can retry with that same ID and unchanged body.

A completed replay retrieves the saved result without another charge. Reusing an ID with a different body returns 409. Generating a new ID inside every retry attempt defeats the purpose because it asks for a new operation.

Distinguish retry from refresh

A saved result belongs to the original operation. If you need a fresh observation of a webpage, create a new operation with a new idempotency key. Replaying yesterday's key is not a request to fetch today's page.

Results are retained for seven days. After expiry, Luni reports the expired result rather than silently rerunning paid work. Your application should decide explicitly whether to purchase a new observation and should keep its own long-term copies when needed.

Handle errors deliberately

A 401 means the key is missing or no longer valid; 403 means it lacks access to the operation; 402 indicates insufficient credits; 409 is an idempotency conflict; 410 reports an expired result; 429 indicates a rate or capacity limit and includes Retry-After; 202 means the work is still running, 424 that it failed and 501 that the feature is not enabled. Inspect the saved operation when you have an ID. A transport interruption or HTTP status alone does not tell you to create a new billable operation.

Keep the original idempotency key when the outcome is unknown or you need to retrieve a completed result. A confirmed failed or cancelled operation stays terminal when you replay its key, including a 429 that asks you to retry with a new operation. After diagnosing the failure, start a deliberate new attempt with a new idempotency key, even if the request body is unchanged. Treat that as new work with a new budget, not an automatic retry of every failure.

For a crawl cancellation, keep already completed results and allow the unused reservation to be released. Use the dashboard's actual operation history to reconcile your queue. The public estimator is a planning aid, not a substitute for settled usage.