Error Codes
The DomShot API uses standard HTTP status codes and returns structured error objects.Error response format
All errors return a JSON object with the following structure:| Field | Type | Description |
|---|---|---|
error | string | Machine-readable error code |
errorDescription | string | Human-readable error message |
Error codes
401 Unauthorized
invalid_token
Invalid or expired API key.inactive_subscription
No active subscription found.402 Payment Required
insufficient_balance
Free tier balance exhausted.429 Rate Limit Exceeded
rate_limit_exceeded
Too many requests within the rate limit window.retryAfter or upgrade your plan for higher limits.
500 Internal Server Error
screenshot_failed
Screenshot generation failed.- Target URL is unreachable
- Page timeout
- Invalid URL
- Internal server error
Status code reference
| Code | Error | Description |
|---|---|---|
| 200 | - | Success |
| 401 | invalid_token | Invalid or expired API key |
| 401 | inactive_subscription | No active subscription |
| 402 | insufficient_balance | Free tier balance exhausted |
| 422 | - | Validation error (invalid parameters) |
| 429 | rate_limit_exceeded | Rate limit exceeded |
| 500 | screenshot_failed | Screenshot generation failed |
Rate limit headers
All responses include rate limit information:| Header | Description |
|---|---|
X-RateLimit-Limit | Requests per minute allowed for your plan |
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Reset | ISO timestamp when window resets |
Troubleshooting
| Issue | Solution |
|---|---|
| Invalid API key | Regenerate in dashboard |
| No active subscription | Subscribe to a plan |
| Rate limit exceeded | Wait or upgrade plan |
| Timeout error | Increase timeout parameter |
| Screenshot blank | Check target URL loads correctly |
| Credits exhausted | Upgrade to paid plan |