Read the error
{
"error": {
"code": "access_denied",
"message": "Access to api.example.com has not been approved.",
"request_id": "00000000-0000-4000-8000-000000000001",
"retryable": false,
"reason": "domain_not_approved",
"action": "Request access to this domain in your dashboard.",
"domain": "api.example.com",
"field": "request.url",
"billing_status": "not_charged"
}
}Keep code and request_id for support. Messages are safe explanations, never raw internal exceptions. Optional reason and action identify the cause and next step. Domain errors include the hostname in domain and the rejected field: source_url or request.url.
| HTTP | Code | Next step |
|---|---|---|
| 401 | unauthorized | Check your Bearer key; do not retry an invalid key unchanged. |
| 402 | insufficient_credits | Top up your wallet or wait for allowance renewal. |
| 403 | access_denied, policies_required, domain_not_approved | Read reason and action; check account access, policies and the rejected hostname. |
| 404 / 405 | not_found, method_not_allowed | Use the documented route and method. |
| 408 | input_timeout | Upload exceeded 20 seconds. Check the connection; no generation charge. |
| 413 | input_too_large | Reduce the upload or individual source/body/profile size. |
| 415 | unsupported_encoding, unsupported_media_type | Send application/json with identity or gzip encoding. |
| 422 | invalid_input, unsupported_profile, unsupported_material, material_expired, generation_failed, generation_incomplete, generation_invalid_headers, generation_invalid_form, output_too_large | Read the specific code and guidance below. Generation errors alone do not establish incorrect client input. SDK 1.1.4+ can re-upload retained material once for explicitly unbilled material_expired. |
| 429 | material_cache_full, rate_limited, concurrency_exceeded, capacity_exceeded | material_cache_full: reuse existing material or wait for cache space; rate_limited: slow requests; concurrency_exceeded: reduce in-flight requests; capacity_exceeded: wait. Respect Retry-After. |
| 503 | credits_warming, generation_unavailable | credits_warming: credits are being prepared. Wait Retry-After: 1 (retryable: true). Otherwise, retain inputs and the request ID. |
| 504 | generation_timeout | Generation exceeded its deadline; retain the request ID. |
Generation failures
These errors describe generation outcomes; they do not establish client fault. Known worker failure codes are preserved. An unrecognized worker 422 becomes HTTP 503 generation_unavailable, rather than invalid client input.
generation_incomplete: generation did not complete. Check that all required scripts, including loader dependencies, are included in execution order. If they are complete, contact support with the request ID.generation_failed: generation failed. Check material completeness; contact support if complete inputs still fail.generation_invalid_headers/generation_invalid_form: generated output failed validation. Contact support with the request ID.output_too_large: generated output exceeded the response limit. Contact support with the request ID.
SDKs use trusted local error wording; upgrade when the corresponding release is available. A successful generation response does not confirm target acceptance.
Account and domain access
A 403 access_denied can include these reasons. Existing policies_required and domain_not_approved codes remain valid.
account_disabled: contact support.account_expired: check account access in the dashboard or contact support.policies_required: accept the current policies in the dashboard.domain_not_approved: request approval for the hostname indomain.domain_pending: wait for review; this reason is returned only when a pending request is known.
Check source and endpoint hosts. A root domain and its www alias share approval; other subdomains need explicit approval.
Retry guidance and billing
error.retryable is optional. A true value identifies a definite temporary error; respect Retry-After, add jitter and reduce concurrency. A false or missing value requires correction or investigation. SDK 1.1.4 retries once only for HTTP 422 material_expired with billing_status: not_charged, while original scripts remain retained. It does not automatically retry any other error or transport failure.
billing_status: not_charged means no allowance or wallet funds were used. pending means the billing record is still updating; it does not confirm a charge. unknown or an absent field means billing could not be confirmed. After a timeout or an uncertain billing outcome, check request history before retrying. Every retry is a new request.
In the dashboard, open Request history, choose a domain and select Details. The panel shows the request ID, recorded HTTP status, timing and next steps. Not charged means no allowance or wallet funds were used. Processing billing refreshes automatically while the final usage record updates. Billing status unavailable means the outcome cannot currently be confirmed; refresh or contact support with the request ID.
Check the inputs before retrying
- For
unsupported_material, check script order, missing dependencies and HTML challenge downloads. - For target rejection, check profile/TLS compatibility, IP continuity, current cookies, exact body and required application headers. If these match, contact support with a sanitized paired exchange. API success alone does not establish target acceptance or client fault.
- A target HTTP 200 can be a challenge page; read the body.
- Pending, unknown or absent billing status never permits an automatic retry. All other generation failures are not automatically retried.
Retry-Afteris a minimum wait, not a reserved slot; its delay is not fixed. - A client timeout can hide a successful generation. Check history before retrying.
Successful generation spends one allowance call or the applicable wallet charge. Failed generations are not billable; usage checks are free. Owners/custom allowances reset Monday at 00:00 UTC; subscription weeks follow billing. For crypto funding or support, contact support@rayonapi.com with sanitized request IDs, not keys, cookies, scripts or generated headers.