ImagePipe answers every failure that happens before response headers are sent
with a status and a short text/plain message. A failure after headers have
been sent abandons the response before it is complete instead, as described
in failures during streaming.
Errors never become cache entries. Telemetry events carry more detail than the response, which deliberately says less.
How statuses are chosen
- 4xx means the request can't succeed as written against this deployment: the URL is malformed or unauthorized, the source doesn't exist, or the source isn't an image ImagePipe will process.
- 5xx means ImagePipe, its host configuration, or the origin failed. The same request may succeed later or on another deployment.
- Sources are concealed. A client learns that a source wasn't found,
couldn't be processed, or that the origin failed. It never learns an origin's
status code, whether ImagePipe's credentials were rejected, or which of
the source's path or network rules refused the request. Those all read as
404 source not found. - One failure, one status. A source that's too large gets
413whether the limit is on its bytes, its pixels, or its frames. - Missing capability is
501. A well-formed request for something this deployment isn't built or configured to do, such as an output format without an encoder or detection without a detector, may succeed elsewhere.
Status table
Request
| Status | When |
|---|---|
400 | The URL doesn't parse, fails validation, names more stored presets than the configuration allows, or names a source scheme that no configured source serves. Validation fails for sig on a server without signing keys, enc/ or wm-enc on a server without source encryption keys, or a detect class that the configured detector doesn't support. The body lists the problems. |
403 | A required signature is missing or wrong. The body is always invalid signature. |
404 | No key on the server decrypts an encrypted source token. |
405 | The method isn't GET, HEAD, or OPTIONS. The response carries Allow. |
410 | The request's expires time has passed. |
500 | A looked-up preset definition is invalid, or the presets that stored definitions reference bring the request above the number of lookups the configuration allows. |
501 | Detection was requested, the configuration requires it, and the detector can't detect the requested classes in this build. When detection isn't required, such requests fall back to attention cropping. |
503 | The preset lookup is unavailable, or detection was requested, the configuration requires it, and the detection models aren't downloaded yet. |
All of these return before source resolution, fetch, or cache access.
Source
| Status | When |
|---|---|
404 | Nothing exists at the source path, or the source's rules refuse it: a path that doesn't match the source's allowed paths, a denied host, address, scheme, or bucket, a directory where a file was expected. Also when the origin answers 401, 403, 404, or 410. |
413 | The source body exceeds max_body_bytes. |
500 | A local file or a cached original exists but can't be read, source credentials are unavailable, or a custom source adapter returns an invalid result. |
502 | The origin is unreachable, answers any other error status, redirects badly, or sends a truncated or malformed response. |
504 | The origin doesn't answer in time. |
Decode and processing
| Status | When |
|---|---|
400 | The request's geometry is impossible for this image, such as a crop region outside it. |
413 | The decoded image exceeds max_input_pixels or declares more frames than allowed. |
415 | The source isn't a supported image. |
422 | The transform can't be applied to this image, its dimensions exceed a native limit, a frame exceeds max_intermediate_pixels when buffered, downsampled, or delivered, or the requested page doesn't exist. |
500 | Encoding failed, detection failed and the configuration requires it, or an unexpected internal error occurred. |
501 | The requested output format has no encoder in this build. |
503 | Processing is overloaded, queued too long, unavailable, or exceeded its deadline. |