Format 404 format_not_found: five causes, including a pending grant

A 404 format_not_found from the Sume Formats API has five documented causes: an unknown handle or slug, an archived Format, a Format outside your key's workspace, a team handle you are not a member of, and a shared Format whose grant is still pending or was removed. The API deliberately returns the same answer for all five.

That is a privacy choice, not a bug, and it is why the fix depends on what you expected to find. This page walks the five causes, using Calling a Format and Errors and spend.

What are the five causes?

The call docs describe the 404 as covering all of these. Work through them in order from cheapest to check.

Why is a pending grant a 404 and not a 403?

A team Format can be shared with another workspace, never a user. The owner adds your team handle on the Format's Access tab, or invites it with POST /v1/formats/{handle}/{slug}/grants, and your admin accepts with POST /v1/format-grants/{grant_id}/accept using a key created in your workspace.

Until acceptance, and again after the owner removes access, the address reads as a 404 for you. The docs say membership of the owner workspace does not stand in for a grant, and a pending or revoked grant reads the same as a Format that never existed.

How is this different from workspace_key_required?

403 workspace_key_required means you are a member of the team workspace but brought a personal key. The docs say a member's team key on the right handle is never this 404, so a 403 workspace_key_required always means right team, wrong key. The docs add that a team key from another workspace is judged by the grant instead: it runs when that workspace holds an accepted grant, and is a 404 when it does not.

Use that as a decision rule. Got a 403? Mint a key in the named workspace (details.workspace_id). Got a 404 with a team handle? Check the grant.

Two related facts from the same pages help when you are unsure which key you are holding. Keys cannot gain scopes after creation, so a key from before the Format API-call trigger shipped may need replacing rather than patching, and a 403 insufficient_scope is never disguised as a format_not_found.

What does a quick diagnosis look like?

Send the same call with each key you hold and compare. The commands below only differ in the key; the path and body stay the same.

for KEY in "$PERSONAL_KEY" "$TEAM_KEY"; do
  curl -sS -o /dev/null -w "%{http_code}\n" -X POST \
    "https://api.sume.com/v1/formats/acme/product-promo/runs" \
    -H "Authorization: Bearer $KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{"instruction":"smoke test"}'
done

Does the same code appear on bulk and reads?

Yes. The Bulk runs page lists the same format_not_found for unknown, archived, outside-workspace and non-member handles, and Format reads follow the same keyed rule: a team key lists that workspace's Formats for every member, and never your personal ones.

Note the safety property. The smoke test above sends a real run create, so use a Format you are happy to run, or a cheap one with a low spend cap. A 404 costs nothing, but a 202 starts work.

If every key returns 404, stop guessing and ask the Format owner for the exact address from the Format page's API tab, and whether the Status is Active. An inactive Format is a different failure (409 format_inactive), so a clean 404 points at addressing or access rather than state.