Sume API error codes by surface: one index with next steps

Sume API error codes are lowercase error.code tokens in one shared envelope: a handful of common codes, such as unauthorized and rate_limited, apply across the API, and the rest are documented per surface: paid generation, Format runs and packages, Scheduled runs, Agent Completions, the media tools, and hosted MCP. Branch on the HTTP status first, then on code, then on next_action.

The codes below come from the docs page for each surface, starting with Errors and rate limits and Errors and spend, read on 2026-09-27. The envelope, the generic codes, and retry advice are covered in Sume API errors and rate limits; this page indexes codes by surface and links the post that explains each group.

Which error codes does each surface return?

Every code in a row appears in the docs for that surface. The sets are open: branch on the codes you handle and fall through on the rest.

Which errors arrive on a receipt instead of an HTTP status?

Three rows above never come back as a 4xx or 5xx on your request. A Format run that returned 202 never turns into a create error later: its failure arrives on the receipt as status: "failed" with an error.code. A bulk item's error is only format_run_failed or format_run_canceled once its child settles, so read the reason on the child run. A failed generation job exposes an error with a category, stage, retryability, and next action.

Some media tool and caption codes also arrive on the failed job rather than the request: the docs mark worker-side refusals such as detach_source_has_no_audio, and caption jobs fail as caption_no_speech or with the two script-alignment codes.

Webhooks follow the same rule. A run receipt over 1 MiB is delivered with payload: null and error.code payload_too_large, while status still reports the run's real outcome.

What should I do next for each code?

An HTTP error's next_action is one of authenticate, fix_input, add_funds, retry_later, poll_status, inspect_events, or contact_support; a failed caption job can also name use_overlay_captions or simplify_script_text_or_omit. In practice:

• Fix the key: unauthorized, insufficient_scope, workspace_key_required. Scopes cannot be added to an existing key, so mint a new one.
• Fix the request: invalid_request, unknown_parameter, output_schema_invalid, and the media tool refusals. A 4xx at Format run create means nothing ran and nothing was charged.
• Add funds: insufficient_credits. Retrying without topping up returns the same answer.
• Wait and retry: rate_limited after retry-after, idempotency_key_in_use after about a second, and provider_capacity_exceeded with the same idempotency key.
• Poll or read the record: run_not_completed means the run is still in flight, so poll status_url. job_not_completed answers any job without a result, so read a failed job's error off GET /v1/jobs/{id}.

Which codes are easy to misread?

A few codes do not mean what their status class suggests:

• 403 insufficient_scope is never 404 format_not_found: a known key missing a scope always gets the 403.
• 404 format_not_found also covers someone else's Format and a shared Format whose grant is pending or removed. The 404 is a deliberate tenancy hide.
• 502 attachment_fetch_failed is your input: next_action is fix_input. Make the URL publicly reachable.
• 503 studio_agent_upstream_unavailable on Scheduled runs reports retryable: false, yet the docs call a bounded retry reasonable.
• An unknown top-level field is 400 unknown_parameter on a Format run, but a Scheduled run silently drops it.
• unsupported_media_type is a non-JSON request body (415) on most routes, but on trim, filter, and detach it means a HEAD of the source URL did not return a video.