API reference
Responses & errors
Headers and status codes you can expect.
Success headers
| Header | Value |
|---|---|
Content-Type | image/avif · image/webp · image/jpeg · image/png · image/svg+xml |
Cache-Control | public, max-age=31536000, immutable |
Accept-CH | Sec-CH-DPR, Sec-CH-Width, Sec-CH-Viewport-Width |
Vary | Accept plus current and legacy image Client Hint headers |
Content-DPR | Resolved DPR when dpr=auto (legacy client compatibility) |
Status codes
| Status | Meaning |
|---|---|
200 | Optimized image returned |
400 | Missing project or source URL |
402 | Cloud only: the project's workspace has no active plan |
403 | Source host is not on the allowlist, resolves to a private/SSRF target, or the project requires signed URLs and sig is missing/invalid |
404 | Unknown project |
413 | Origin image exceeds the size cap (KEENPIX_MAX_ORIGIN_BYTES) |
502 | Origin fetch failed |
503 | A proxy admission limit or an unhealthy service dependency refused the request; inspect Retry-After and private readiness checks |
504 | Origin request timed out (KEENPIX_ORIGIN_TIMEOUT_MS) |
A 403 almost always means the source host isn't on the project's allowlist — add it
under Settings → Security → Allowed hosts. If the project requires signed URLs, a
403 also fires for a missing or invalid sig parameter.