402 insufficient_credits: read required and available credits

When a Sume paid request returns 402 insufficient_credits, the error body tells you the exact gap: details.required_credits is what the request needs and details.available_credits is what the workspace has now, both as whole credits. Subtract one from the other to get the shortfall, stop submitting, and retry only after credits are added (docs.sume.com, read 2026-10-13).

Sume answers this before any provider work starts, so a 402 at submit means nothing ran. The docs say all usage is in credits, so the body carries no dollar or cents field to convert.

What does the 402 body contain?

The envelope is the standard Sume error object with a request_id. On Format runs it also carries next_action: "add_funds". An organization workspace without a provisioned wallet gets a different code, organization_wallet_not_provisioned, with the same details.

How do I compute the shortfall in Python?

This helper takes the HTTP status and raw body, returns the missing credits for an insufficient_credits error, and returns None for anything else. It uses only the standard library.

With the documented example body (150 required, 40 available) it returns 110.

import json

def shortfall(status: int, body: str):
    """Return missing credits for a 402 insufficient_credits, else None."""
    if status != 402:
        return None
    err = json.loads(body).get("error", {})
    if err.get("code") != "insufficient_credits":
        return None
    d = err["details"]
    return max(0, d["required_credits"] - d["available_credits"])

What should the caller do next?

Treat the 402 as a stop signal, not a retry signal. The Formats docs say that if you retry before you add credits, you get the same answer. Credits come from a plan upgrade, or from a purchase on a team workspace; buying credits is a dashboard operation, not an API call.

• Stop launching new submits in the batch and record the request_id of the 402.
• Log the shortfall so a person knows how many credits to add.
• After credits arrive, resubmit with the same Idempotency-Key. A failed create releases its key on Format runs.
• Do not confuse it with 429 queue_full or 429 rate_limited: those are retried with backoff, a 402 is not.

Why not parse the message text?

The message is for people and can change. Branch on the HTTP status and error.code, and read numbers only from details. The Formats docs make the same point for every code.