Sume Format list empty or 404? Check which key you are using first

Start with the key

If a Sume Format you know exists comes back as empty or 404, check which API key you sent before anything else. A Format belongs to a handle and a workspace, and a key belongs to one workspace. A personal key does not see a team's Formats, and a team Format needs a key issued in that team's workspace.

A 403 with workspace_key_required is the clearest hint: you found the right team, but your key is for the wrong place. Service-account keys are refused for Formats entirely.

Read the response

The table maps each response to a next step, as of 2026-10-08.

Check it with curl

List what this key can see, then compare to what you expect. The key needs formats:read. Print only the fields you need so a long list stays readable.

curl -sS https://api.sume.com/v1/formats \
  -H "Authorization: Bearer $SUME_API_KEY" | jq .

Common causes

The usual culprits are a key copied from the wrong workspace, a CI secret that still holds an old key, and a slug typed from memory. For catalog Formats, only the 27 listed sume- slugs exist at the sume handle, and any other slug answers 404.

Rotate by creating a key in the right workspace, update the secret, and call the list again. Do not add a workspace id to your requests: the key selects the workspace, and no parameter overrides it.

• Confirm scopes: formats:read to list, formats:write to run.
• Check which environment you are calling: production and dev hosts have separate keys.
• Include the request id when you ask support for help.

If the list is right but the run fails

A visible Format can still refuse a run. formats:write may be missing from the key, the body may exceed 4 MiB (413), or Idempotency-Key may be absent. Each has a distinct status, so read the error code before you change keys again.

Treat these as working notes you can adapt: the figures are from the Sume docs read on 2026-10-08, and the arithmetic is yours to rerun with your own numbers.

Make it routine

Add this check to your runbook and run it on a schedule, not only after an incident. The cost is a few read requests, and the rate limits are far above what it needs: even the Free plan allows 120 writes and 4,800 reads per minute. Keep the output with the date, so you can show later what the system looked like when a question came up.

A personal key can run Formats in your personal space. If you also belong to a team, the team's Formats are in a different workspace, and the matching key must come from there. The docs note that confusing the two used to produce runs in the wrong place, so name keys after their workspace when you create them, for example ci-team-formats.

• Name keys by workspace.
• Keep one key per environment.