Four status vocabularies in the Sume API: job, resource, run, delivery

A client that mixes Sume's status words will misread what it sees. The API has separate vocabularies for jobs, resources, runs and webhook deliveries, and the same word can mean different things on each. This is the short version, taken from the Errors and Jobs pages.

Use the booleans where you can. A job status carries terminal and result_ready, and the polling guidance is to branch on those or on sume_status, not on a free-form string.

The traps

The first trap is delivery versus outcome. A webhook delivery in exhausted means that Sume used all attempts to reach your endpoint. The job or run is still in its real terminal state, and you read it from status_url or result_url.

The second is ready. A resource such as an avatar is ready, not completed. The third is a run's OK: on a webhook envelope, status: OK means the run completed, but outcome can still be degraded when real artifacts exist and the structured output could not be built.

A small switch

Keep one function per object type and do not share a switch. A job handler should end on terminal. A run handler should read outcome. A delivery monitor should alert on exhausted, then use Redeliver, which does not consume one of the automatic ten attempts.

• Job: stop polling on terminal; read result_ready before fetching the result.
• Run: canceled and skipped runs send no webhook, so poll status_url for them.
• Delivery: retrying is normal; exhausted needs your action.
• Never match on message text; branch on code and status.

Mapping to your own states

Most teams collapse these into three internal states: waiting, done, and needs attention. Waiting covers queued, processing, pending, delivering and retrying. Done covers completed, ready and delivered. Needs attention covers failed, exhausted, and a run outcome of degraded. Canceled is its own case, since a canceled run sends no webhook.

Keep the raw value next to your mapped one in logs. When the API adds a status, an exact-match switch with no default will fail quietly, so give it a default that routes to a human.

Treat this as a habit, not a one-time fix. Write the rule down next to the code that calls the API, add a test that exercises it, and review it whenever the docs change. Check the linked documentation pages in the sources list for the current wording before you rely on any number here, because limits and field names can be revised, and a short test run costs far less than debugging a production incident.

When something does not match what you read here, capture the x-sume-request-id response header and the job or run id, and send those to support. Do not paste API keys, signing secrets or full request bodies into a ticket or a chat; the ids are enough for the team to find the request.