Map a Sume API HTTP status to the next step: one Python function

This function returns the next step for the status codes and error codes in the Sume docs: wait, retry with the same Idempotency-Key, fix the request, or stop. It reads retry-after when it is there and falls back to your own backoff when it is not.

def action(status, code, headers=None):
    """Map a Sume HTTP error to what the client should do next."""
    headers = headers or {}
    if status == 429 and code == "queue_full":
        return "wait: a queued or processing job must finish or be canceled, then resend with the same Idempotency-Key"
    if status in (429, 503) and code != "provider_not_configured":
        wait = headers.get("retry-after", "backoff")
        return f"retry after {wait} with the same Idempotency-Key"
    table = {
        400: "fix the request; do not retry",
        401: "fix the credential (send exactly one of x-api-key or Authorization)",
        402: "add funds or lower the cost; do not retry",
        404: "check the id and the workspace; do not retry",
        409: "read the job; do not resubmit",
        413: "shrink the body; do not retry",
        415: "send application/json; do not retry",
        503: "do not retry aggressively; check runtime status",
    }
    return table.get(status, "log the request_id and stop")


if __name__ == "__main__":
    print(action(429, "rate_limited", {"retry-after": "7"}))
    print(action(429, "queue_full"))
    print(action(503, "provider_capacity_exceeded"))
    print(action(409, "job_not_completed"))

What it prints

Run it as it stands and it prints four lines: retry after 7 seconds, wait on queue_full, retry a 503 provider_capacity_exceeded with backoff, and read the job on a 409.

Cases covered

The table shows the cases the function covers.

Why queue_full is special

A 429 is not always a reason to wait on the clock. queue_full means Sume cannot accept another paid generation job until a current one finishes or is canceled; a timer alone may not help. Full concurrency by itself is not an error, because Sume queues valid jobs while queue capacity remains.

The key

Do not retry a submit without an Idempotency-Key. Pass the same key on every retry for one intent, and the retry returns the original job.

The default

Anything the function does not know returns "log the request_id and stop". The error body and headers carry a request id; include it when you ask for help, and leave out keys and signed URLs.