Responses and errors

The headers of a chop response and what each status code and error message means.

Open as Markdown

Every success is a 200 with the headers a cache needs, and every error is plain text that is never cached. A successful request for the test image at 300 pixels wide with Accept: image/avif, then a request for a file that doesn't exist:

HTTP/1.1 200 OK
content-type: image/avif
content-length: 2642
etag: "<etag>"
cache-control: public, max-age=31536000
vary: Accept
chop-status: transformed
x-content-type-options: nosniff
chop-bytes-saved: 516645
HTTP/1.1 404 Not Found
content-type: text/plain; charset=utf-8
cache-control: no-store
x-content-type-options: nosniff

Not found.

A path that tries to leave the data directory is refused before any file is read:

curl --path-as-is -i 'http://localhost:8080/../etc/passwd'
HTTP/1.1 400 Bad Request
content-type: text/plain; charset=utf-8
cache-control: no-store
x-content-type-options: nosniff

Invalid path.

Reference

A success is 200 with the Content-Type of the output, Content-Length, Cache-Control: public, max-age=<maxAge>, Vary: Accept, X-Content-Type-Options: nosniff and a strong ETag based on a SHA-256 of the image bytes and the Chop header values. An If-None-Match that matches the ETag (weak comparison, lists and *) gets 304 with the same ETag, Cache-Control and Vary and no body. A HEAD response has the headers of the GET response, including Content-Length, and no body.

  • Chop-Status is transformed when Chop serves the encoded image, even if it is larger than the original. It is passthrough when Chop serves the original bytes. The header appears on image responses, including HEAD and 304, and its value contains no Chop version.
  • Chop-Bytes-Saved is the original size minus the output size, in bytes. It appears on 200 image responses only when the output is smaller. If your client reads X-Bytes-Saved, update the client and check your caches.

Errors are plain text with a short message that doesn't reveal file system paths, Cache-Control: no-store and X-Content-Type-Options: nosniff.

Status codes

Status Message Meaning
400 Invalid "w" argument: expected a whole number., Invalid path. Invalid request: an unsafe path, a malformed argument, a size over maxOutputDimension or a width that isn't in allowedWidths.
404 Not found. Not found: a missing file, a directory, or a path that resolves outside the data directory, which all look the same. For a remote origin also an upstream 404, 410, 401, 403 or 407, a URL source that isn't allowed and a destination at a blocked address.
405 Method not allowed. A method other than GET and HEAD, with Allow: GET, HEAD.
413 The original image is too large. The original is over maxInputBytes, which is checked before the file is read.
415 This file is not a supported image. The file is not a JPEG, PNG, GIF, WebP or AVIF image.
422 The image can not be processed., The image can not be read. The image is corrupt, or has more than maxInputPixels pixels.
500 Plain text An unexpected error.
502 Plain text The origin failed: it couldn't be reached, it answered with a 5xx or another unexpected status, it redirected, or it sent a compressed or incomplete body.
503 Plain text The queue of images or of downloads is full, with Retry-After: 1.
504 Plain text The origin was too slow to connect or to send the whole image.

The error statuses 502 and 504 also have Cache-Control: no-store, as every error does. Each path segment is percent-decoded once, and a segment that is . or .., is empty, or contains /, \ or a NUL byte after decoding is a 400. The real path of the file, with symbolic links resolved, must be inside the real path of the data directory.