403 insufficient_scope on a Sume Format run: scope or service key

A 403 insufficient_scope on a Sume Format call has two causes: the key does not carry formats:write (or formats:read for a read), or it is a service-account key, which cannot create Format runs at all. Both are fixed the same way: create a new key. Scopes cannot be added to an existing one.

The rules are from Create a run, Errors and spend and Bulk runs, read 2026-09-29.

How do I tell which cause I have?

Read the error body. A missing scope names itself in details.required_scope. A service-account key carries details.reason set to service_account_format_runs_unsupported. In both cases next_action is authenticate.

Which scope does each call need?

formats:write creates a run, creates a bulk queue, cancels a run and redelivers a webhook. formats:read lists and reads Formats, reads and lists runs, and reads queues. So a key that can poll a run may still fail the create that started it. This read needs only formats:read; a 403 here names formats:read in details.required_scope.

curl -sS "https://api.sume.com/v1/formats/sume/sume-product-commercial" \
  -H "Authorization: Bearer $SUME_API_KEY" | jq '.error | {code, details}'

Why do old keys fail?

Keys created before the Formats API shipped do not carry these scopes. The docs say scopes are fixed when a key is created and cannot be added later, so an old key fails every Format request with 403 insufficient_scope, never a 404. Create a new key in the API keys dashboard and rotate to it.

How do I fix a service-account key?

A service-account key cannot be repaired by adding scopes, because the block is on the key type, not on the scope list. Create a new key in the API keys dashboard with the Format scopes and use that for Format runs. Keep the service-account key for whatever else it was made for, and give your Format integration its own key with formats:read and formats:write. One key per integration also makes it easy to revoke a single caller later.

Is it a 403, a 401 or a 404?

A missing, malformed, revoked or unknown key is 401 unauthorized. A known key missing a scope is 403 insufficient_scope, and a wrong Format address is 404 format_not_found. A 403 workspace_key_required is a different problem: a team Format called with a personal key, fixed with a key created in the team's workspace. The wider comparison is in 401 vs 403 vs 404.

A failed create costs nothing: the docs say a 4xx at create is not charged and releases the Idempotency-Key.