Skip to main content

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:
{
  "error": "error_code",
  "errorDescription": "Human-readable error message"
}
FieldTypeDescription
errorstringMachine-readable error code
errorDescriptionstringHuman-readable error message

Error codes

401 Unauthorized

invalid_token

Invalid or expired API key.
{
  "error": "invalid_token",
  "errorDescription": "The API key is invalid or expired"
}
Solution: Check your API key in the Dashboard.

inactive_subscription

No active subscription found.
{
  "error": "inactive_subscription",
  "errorDescription": "No active subscription found"
}
Solution: Ensure you have an active subscription.

402 Payment Required

insufficient_balance

Free tier balance exhausted.
{
  "error": "insufficient_balance",
  "errorDescription": "Free tier balance exhausted. Please upgrade your plan."
}
Solution: Upgrade to a paid plan to continue using the service.

429 Rate Limit Exceeded

rate_limit_exceeded

Too many requests within the rate limit window.
{
  "error": "rate_limit_exceeded",
  "errorDescription": "Rate limit exceeded. Try again at 2024-01-01T12:00:00.000Z",
  "retryAfter": 30
}
Solution: Wait for the number of seconds specified in retryAfter or upgrade your plan for higher limits.

500 Internal Server Error

screenshot_failed

Screenshot generation failed.
{
  "error": "screenshot_failed",
  "errorDescription": "Failed to load the target URL"
}
Causes:
  • Target URL is unreachable
  • Page timeout
  • Invalid URL
  • Internal server error
Solution: Verify the target URL is accessible, try increasing the timeout parameter, or contact support if the issue persists.

Status code reference

CodeErrorDescription
200-Success
401invalid_tokenInvalid or expired API key
401inactive_subscriptionNo active subscription
402insufficient_balanceFree tier balance exhausted
422-Validation error (invalid parameters)
429rate_limit_exceededRate limit exceeded
500screenshot_failedScreenshot generation failed

Rate limit headers

All responses include rate limit information:
HeaderDescription
X-RateLimit-LimitRequests per minute allowed for your plan
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetISO timestamp when window resets

Troubleshooting

IssueSolution
Invalid API keyRegenerate in dashboard
No active subscriptionSubscribe to a plan
Rate limit exceededWait or upgrade plan
Timeout errorIncrease timeout parameter
Screenshot blankCheck target URL loads correctly
Credits exhaustedUpgrade to paid plan