05 // BILLING GUIDELINES & POLICIES
ERRORS & REFUNDS
Official API response error definitions, credit deduct rules, and balance adjustment guidelines.
1. Error Code Registry & Diagnostics
| Code | HTTP Status | Reason / Trigger | What to do next |
|---|---|---|---|
UNAUTHORIZED |
401 | API key is missing, malformed, or has been revoked. | Verify headers or rotate key in the `/portal`. |
PAYMENT_REQUIRED |
402 | Your token credit balance has run out. | Transfer UPI/GPay and submit UTR ref in `/portal`. |
FORBIDDEN |
403 | Your key lacks the necessary path scope permission. | Ensure scope list matches in the Admin issuer panel. |
TOO_MANY_REQUESTS |
429 | IP rate-limit ceiling or key daily limits breached. | Back off and retry using exponential backoff. |
SERVICE_UNAVAILABLE |
503 | Headless scraper pool is running at peak capacity. | Delay retries by 10s using random jitter spacing. |
SERVER_ERROR |
500 | The Chromium runner encountered a target page crash. | Verify the target URL domain resolves to a public space. |
2. Credit Deduction & Billing Rules
-
Pre-Deduction Model: Credits are checked and deducted immediately upon starting a scrape job. This prevents queue choking and secures resource allocations.
-
Rejections are Zero-Cost: Requests rejected before browser boot—such as rate-limits (429), expired keys (403), or capacity overflow (503)—consume 0 credits.
-
Target Failures are Billable: If a scrape job times out or fails because the target URL resolves to private IP addresses (SSRF block) or blocks headless agents, the deduction stands as computing resources were utilized.
3. Automatic & Manual Refunds
Full System Fault Refunds (5 Credits):
If a Deep Mode job fails completely due to an internal system fault (e.g. database disconnect, container reboot, or worker scraper crash) before delivering raw styles, our background monitor catches the error state and triggers an immediate automatic refund of 5 credits back to your API key balance.
If a Deep Mode job fails completely due to an internal system fault (e.g. database disconnect, container reboot, or worker scraper crash) before delivering raw styles, our background monitor catches the error state and triggers an immediate automatic refund of 5 credits back to your API key balance.
Partial Upstream AI Refunds (1 Credit):
In Deep Mode, if the target page is successfully scraped and raw design deliverables are saved, but the upstream Gemini AI model fails due to a rate limit or timeout, the system delivers the raw tokens and ZIP skill pack without AI annotations. In this case, 1 credit is automatically refunded to your key, resulting in a final charge of only 4 credits.
In Deep Mode, if the target page is successfully scraped and raw design deliverables are saved, but the upstream Gemini AI model fails due to a rate limit or timeout, the system delivers the raw tokens and ZIP skill pack without AI annotations. In this case, 1 credit is automatically refunded to your key, resulting in a final charge of only 4 credits.
Manual Adjustment Path:
If you believe a scrape failed due to a platform issue but did not trigger an automatic refund, please copy your Request ID and send details to our operators via Support. Valid claims are verified against the audit log and credited within 24 hours.
If you believe a scrape failed due to a platform issue but did not trigger an automatic refund, please copy your Request ID and send details to our operators via Support. Valid claims are verified against the audit log and credited within 24 hours.