All API endpoints return JSON error bodies with a consistent structure. Below are the common error codes across all endpoints.
Error Reference
| Code | Error | Description |
|---|---|---|
| 400 | invalid_domain |
Domain is empty or not a valid hostname |
| 400 | invalid_origin_host |
Origin host does not normalize to a valid hostname |
| 400 | origin_host_same_as_domain |
Origin host cannot be the same as the domain itself |
| 400 | origin_host_is_editor_url |
Origin host is an editor URL; use your published project URL instead |
| 400 | redirect_limit_reached |
Redirect rule limit for your plan exceeded (response includes limit and current) |
| 400 | invalid_custom_headers |
Custom response header rules failed validation (response includes details) |
| 400 | fetch_failed |
Sitemap URL could not be fetched |
| 400 | parse_failed |
Sitemap did not return valid XML sitemap content |
| 401 | missing_api_key |
No API key provided in headers |
| 401 | invalid_api_key |
API key is invalid or revoked |
| 403 | plan_required |
Your plan does not include this API (response includes requiredPlan) |
| 403 | requires_unscoped_key |
Endpoint requires an account-wide API key, not a domain-scoped one |
| 403 | domain_not_owned |
Target domain is not connected to your account (does not apply to API Platform users) |
| 403 | api_key_domain_scope_mismatch |
API key is valid but scoped to a different domain |
| 403 | domain_suspended |
Domain is suspended and cannot be re-added |
| 403 | domain_limit_reached |
Plan domain limit reached; add slots from the dashboard or upgrade |
| 403 | upgrade_required_for_custom_headers |
Your plan does not include custom response headers |
| 403 | no_seo_spider_access |
Your plan does not include SEO Spider access |
| 403 | on_demand_limit_reached |
Monthly on-demand SEO audit limit reached |
| 403 | prompt_limit_reached |
Plan prompt monitor allocation exceeded. Upgrade your plan or deactivate existing prompts. |
| 409 | run_already_active |
An SEO audit is already running for this domain |
| 409 | domain_already_connected |
Domain is already connected to an account |
| 429 | rate_limited |
Too many requests for this API key; back off and retry |
| 503 | service_unavailable |
Domain configuration could not be applied; retry the request |
Best Practices
- Send Accept header — Always include
Accept: text/htmlfor bot/crawler requests to maximize prerender success. - Rotate API keys — Regularly rotate and revoke compromised keys from your dashboard.
- Use prewarm wisely — Enable prewarm for critical pages to ensure instant cache hits after invalidation.
- Handle 304 responses — When you get a 304, follow the
Locationheader or fetch directly from origin.
API Collections
Explore and test the API using these interactive platforms:
