organization_wallet_not_provisioned vs insufficient_credits (402)

Both are 402 on create and both mean nothing ran. insufficient_credits says the workspace wallet cannot fund the run, so top it up; organization_wallet_not_provisioned says an organization workspace has no funded wallet at all, so an admin has to fund it. The distinction matters because the person who sees the error is rarely the person who can fix it.

What are the two 402 codes?

The Formats errors page lists the wallet as the gate that applies at create. The workspace must be able to fund the run, or the create fails before anything is spent.

The first code is for a workspace that exists and is funded but is too low. The second is for an organization workspace that has never been given a wallet.

Why does a team key matter here?

A Format owned by a team workspace is invoked with an API key created in that workspace. The docs state the rule "follows the money": the team Format's runs bill the team wallet, count against the team's generation concurrency, and read media through the team workspace. A personal key held by a team member is refused with 403 workspace_key_required, which is a different error from either 402.

The changelog for v0.2.59 lists "Org / team pooled wallet and team concurrency controls", which is the feature this error belongs to. If you are the engineer and not the admin, the useful move is to send the admin the workspace id and the code, not the key.

How should a client handle both?

Branch on error.code, not on the status alone. Retrying a 402 will not help; the same idempotency key is released after a failed create, so once the wallet is funded you can resend the identical request and get the run.

The snippet below maps the two codes to the right owner. It only reads error.code, which is the documented envelope field.

import json, urllib.error, urllib.request

OWNER = {
    "insufficient_credits": "top up the workspace balance",
    "organization_wallet_not_provisioned": "ask an org admin to fund the wallet",
}

def explain(req: urllib.request.Request) -> str:
    try:
        urllib.request.urlopen(req, timeout=30)
        return "accepted"
    except urllib.error.HTTPError as e:
        if e.code != 402:
            return f"HTTP {e.code}"
        code = json.load(e).get("error", {}).get("code", "")
        return OWNER.get(code, f"402 {code}")

What does this not tell you?

It does not tell you how much to add. For that, read the rate card, size the run's spend cap, and check GET /v1/balance. A wallet that clears the create gate can still hit the run's own spend cap later, which ends the run as failed, and the two controls are separate: see Spend caps.