Return 4xx for undecodable/corrupt images instead of 500

[JasonWildMe]

Summary

Inference endpoints returned HTTP 500 for a corrupt/undecodable input image, which made a permanent failure look transient to clients and could stall downstream pipelines.

Root cause: a corrupt image (e.g. a JPEG with a valid header but a broken entropy-coded scan stream — broken data stream when reading image file / Unsupported marker type 0xNN) fails during PIL decode inside model.predict/extract. The routers catch that with their generic except Exception → 500. Wildbook (the caller) classifies any 5xx as retryable and re-queues the job — so a permanently-bad image is retried indefinitely and the asset never reaches a terminal state (observed as a bulk import stuck at 99% detection).

Fix: reject an undecodable image as a 4xx (client error) so callers treat it as permanent / non-retryable.

• app/utils/image_uri.py: add ImageDecodeError(ValueError) and validate_decodable(), which fully Image.open(...).load()s the bytes (a header-only verify() would miss broken scan streams) and raises ImageDecodeError on UnidentifiedImageError / OSError / DecompressionBombError.
• predict, pipeline, extract, classify routers: call validate_decodable(image_bytes) right after resolve_image_uri(...), inside the existing except ValueError → HTTP 400 block. Since ImageDecodeError subclasses ValueError, an undecodable image now returns 400 instead of escaping to the generic 500.

Test Plan

• tests/test_image_decode_validation.py (pure PIL, no GPU) — valid image passes; corrupt-marker, non-image, empty, truncated, and decompression-bomb inputs all raise ImageDecodeError; ImageDecodeError is a ValueError. 7/7 pass locally.
• CI / model env: endpoint-level check that a corrupt image returns 400 (not 500) from /predict/, /pipeline/, /extract/, /classify/, and that inference is not invoked. (Router 400 contract verified by inspection; endpoint tests need the model/GPU environment.)

Notes

• Trade-off: the validator decodes the image once and the model decodes again (~2× decode time, negligible vs GPU inference). Accepted for the robustness gain; a future optimization could share one decoded representation.
• Status choice: reuses the routers' existing image-input convention (400). A dedicated 422 would be marginally more semantic, but any 4xx achieves the non-retryable classification.
• Companion Wildbook-side change (WildMeOrg/Wildbook#1609) rejects corrupt bulk-import images before they reach ml-service; this PR is defense-in-depth for images that arrive via other paths or pass Wildbook's (Java ImageIO) decoder but fail ml-service's (PIL) decoder.

🤖 Generated with Claude Code