Error codes and response shapes.
Errors return JSON with a code, a message and a request_id for support requests. HTTP status codes follow standard REST conventions. Every error includes a docs_url pointing back to this page anchor for the specific code.
// Section 01 · Error envelope
Standard error response shape.
Every error response uses the same envelope. The error object carries code, message, request_id (for support), and a docs_url that anchors to this page. Always log the request_id when handling errors so support can trace the request quickly.
{
"error": {
"code": "audit_quota_exceeded",
"message": "Tier quota exceeded for the current period",
"request_id": "req_2HxJ4nP3kqM8f3k",
"docs_url": "https://www.crawlux.com/docs/errors/#audit_quota_exceeded"
}
}// Section 02 · 4xx Client errors
Errors your code should handle.
invalid_domainDomain format invalid or domain unreachable. Common causes: missing protocol (use https://example.com not just example.com), typo, DNS not propagated, domain blocked by registrar. Verify the domain resolves to a public IP before retrying.
invalid_requestRequest body malformed. Common causes: missing required field, wrong content-type, JSON parse error. The error message identifies the specific field at fault.
invalid_api_keyAPI key missing, malformed or revoked. Check the Authorization header format (must be exactly Bearer crl_...). Regenerate the key from the dashboard if compromised. Key revocation takes effect within 30 seconds.
tier_requiredThe requested feature requires a higher tier. Common cases: webhook configuration on free tier (Pro or Team required), PDF download on free tier (Pro or Team required), IP allowlisting on Pro tier (Team required). The error message identifies the minimum tier needed.
audit_not_foundNo audit with the requested audit_id exists in your workspace. Either the audit was triggered with a different workspace, never existed, or was deleted (audits older than 24 months are pruned for free tier).
audit_quota_exceededMonthly audit quota exhausted for the current tier. Wait until the period resets (X-RateLimit-Reset header gives the timestamp) or upgrade tier. Result retrieval calls are not affected.
burst_limit_exceededMore than 10 audits triggered within 60 seconds. Wait 60 seconds and retry. Usually indicates a loop bug. See rate limits.
// Section 03 · 5xx Server errors
Errors to retry with backoff.
internal_errorUnexpected server error. Include the request_id when contacting support. Retry with exponential backoff. Sustained 500s mean Crawlux infrastructure is having issues; check the status page.
// Section 04 · Webhook delivery errors
Errors specific to webhook callbacks.
Webhook delivery failures do not generate API error responses; they appear in your dashboard webhook delivery log. The audit itself still completes and the JSON remains retrievable via the dashboard or GET /audits/{audit_id}. Failed deliveries can be retried manually from the dashboard for 7 days. The audit.failed webhook event has its own error envelope inside the payload; see the webhooks reference.
// Section 05 · Reporting bugs
When an error looks wrong.
If you encounter an error that does not match this reference or seems incorrect, send the request_id and the full error response to [email protected]. Bug-grade error reports skip the regular support queue and are triaged by the engineering team directly.
// Related docs
Where to go from here.
- REST API reference — endpoint surface
- Rate limits — quota details
- Status page — provider outages and service health
- Support — how to escalate
Run a free audit and download the JSON
The fastest way to evaluate the audit JSON for integration: run a real audit on your own domain and inspect the output. Free first audit per domain.
JSON output live · Webhooks live · API Q4 2026 · 2-week early access window