Error Codes Reference

All API error responses return a standardized JSON structure with an HTTP 4xx or 5xx status code.

{
  "error": {
    "code": "invalid_parameter",
    "message": "title must be 1-120 characters",
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "details": [
      {
        "param": "title",
        "issue": "too_long",
        "message": "title exceeds maximum allowed length of 120 characters"
      }
    ]
  }
}

Every response includes a unique request_id (mirrored in the x-request-id response header) to assist in debugging and customer support.

---

Error Codes Table

Error Code	HTTP Status	Root Cause	Recommended Fix
missing_parameter	400	A required query parameter (such as title) was not provided.	Ensure title is supplied in the URL query string (e.g. ?title=My+Title).
invalid_parameter	400	A parameter value failed validation (e.g. title > 120 chars, invalid hex color, unknown font/theme/size).	Review the Parameters Reference for allowed lengths, formats, and enums.
unknown_parameter	400	An unrecognized query parameter was passed in the URL (strict fail-closed parameter validation).	Remove extra query parameters or check for typos in parameter names.
turnstile_failed	403	Cloudflare Turnstile bot verification token was missing, invalid, or expired on an interactive tool form.	Complete the Turnstile challenge widget on the page and submit again.
unknown_layout	404	The layout specified in /v1/images/{layout}.png does not exist.	Use one of the registered layout IDs: minimal, article, docs, product, profile, announcement.
not_found	404	The requested API route does not exist.	Check the API endpoint path against the API Reference.
method_not_allowed	405	The HTTP method is not permitted on this route (e.g., sending a POST request to an image render route).	Use the supported HTTP method (e.g., GET or HEAD for image generation endpoints).
uri_too_long	414	The entire request URL exceeds the maximum allowed length of 2,048 bytes.	Shorten long descriptions or title strings; remove unnecessary query parameters.
remote_asset_blocked	422	SSRF defense blocked a remote asset (logo or avatar) because it points to a private/loopback IP, cloud metadata, or non-HTTPS scheme.	Host remote images on a publicly routable HTTPS CDN using port 443. Private IPs (RFC 1918) are strictly forbidden.
remote_asset_failed	422	Failed to fetch or decode remote image (unsupported image format, file > 2 MB, dimensions > 4096×4096 px).	Ensure the remote asset is a valid PNG or JPEG under 2 MB with dimensions not exceeding 4096×4096.
target_unreachable	422	DNS resolution failed or the target server could not be reached during page or image inspection.	Verify that the target domain name is registered, active, and reachable on the public internet.
target_blocked	422	Target address inspected by developer tools resolved to a private or disallowed network address.	The URL inspected must resolve to a publicly accessible IP address.
rate_limited	429	Anonymous request quota exceeded (60 renders/min per IP, 1,000 renders/day per IP hash).	Delay subsequent requests by the number of seconds specified in the Retry-After header.
internal_error	500	An unhandled exception or internal error occurred while rendering the image.	Contact support with the request_id from the response for investigation.
category_not_enabled	501	The requested feature category (e.g. screenshot or ai) is not currently enabled.	Use the static template generation endpoints. Follow the roadmap for planned features.
capacity_exceeded	503	Edge rendering concurrency limit reached under heavy global load.	Retry your request using exponential backoff.
dependency_unavailable	503	An internal edge dependency (such as storage or KV) was temporarily unreachable.	Retry the request after a short interval.
upstream_timeout	504	Downloading an external remote image or inspecting a target URL exceeded the 3-second deadline.	Ensure upstream image servers respond promptly within 3,000 milliseconds.

---

Client Error Handling Pattern (TypeScript)

When fetching images or using API routes programmatically, inspect the HTTP status code and parse the error response:

async function fetchImageSafe(url: string): Promise<Blob> {
  const response = await fetch(url);

  if (!response.ok) {
    if (response.status === 429) {
      const retryAfter = Number(response.headers.get("retry-after") ?? "60");
      throw new Error(`Rate limited. Try again in ${retryAfter} seconds.`);
    }

    const errorJson = await response.json();
    throw new Error(
      `API Error [${errorJson.error.code}]: ${errorJson.error.message}`
    );
  }

  return response.blob();
}