POST /v1/images status codes on Sume: 200, 202, 400, 404, 502

A client for POST /v1/images needs five branches, not two. The route waits up to 30 seconds by default (mode: "sync", wait_timeout_seconds: 30) and answers according to what happened inside that window. Facts below are from the Sume Image API docs, read 2026-10-07.

The five outcomes

Two traps

First, 202 is not an error. Slow configurations (4K, high or higher quality, large n) are the likeliest to fall out of the 30-second window. Check the status code, not whether data exists in the body.

Second, 502 carries the same remapped error fields as the job status route, including retryable and next_action. A reference URL that cannot be fetched gives a non-retryable input_media_unreachable with next_action: "fix_input"; do not blindly retry it. In async or webhook mode a failed job does not become a 502, because the job is the answer.

A client that branches

import os, requests
H = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"]}
r = requests.post("https://api.sume.com/v1/images", headers=H, timeout=60,
                  json={"model": "bytedance-seed/seedream-5-lite", "prompt": "a paper boat"})
if r.status_code == 200:
    print([d["url"] for d in r.json()["data"]])
elif r.status_code == 202:
    print("poll", r.json()["data"]["result_url"])
elif r.status_code == 502:
    e = r.json()["error"]
    print(e["code"], e["retryable"], e["next_action"])
else:
    print(r.status_code, r.text[:200])

Sources: Sume Image API docs and Jobs and results (read 2026-10-07).