IN_QUEUE or queued? Two status fields on a Sume job, do not mix

The status endpoint on Sume jobs returns two ways to say the same thing, and the jobs page says never to mix them. sume_status is queued, processing, completed, failed or canceled. A queue-shaped status field uses IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED and CANCELED, and maps one to one onto sume_status for clients ported from other queue APIs. They never disagree. Poll on the booleans terminal and result_ready, or on sume_status, and pick one.

There is a third vocabulary for video submitted through /v1/videos, and it is the one that surprises people.

Three vocabularies side by side

From the jobs and video pages, read 2026-10-03.

Which one should I poll on

Use terminal for the loop and result_ready for the fetch. A boolean cannot be misspelled, and it does not change when the vocabulary differs between routes. Use sume_status when you need the label, for display or for a switch on completed versus failed versus canceled.

Do not compare strings across surfaces. A check for "canceled" will miss "cancelled" on a /v1/videos poll, and a check for "queued" will miss "pending". If your code reads both routes, normalize once at the edge and keep a single internal enum.

A small normalizer

After normalizing, the rest of the pipeline never needs to know which route produced the job. The same job is readable at both GET /v1/videos/{jobId} and the jobs endpoints.

• Map pending, queued and IN_QUEUE to your internal queued state.
• Map in_progress, processing and IN_PROGRESS to running.
• Map completed and COMPLETED to done, failed and FAILED to failed.
• Map cancelled, canceled and CANCELED to canceled.

Why the result route is separate

GET /v1/jobs/{id}/result is only for completed jobs and answers 409 job_not_completed otherwise, so read the failure off the job record, not off the result route. On failure, read GET /v1/jobs/{id} and its job.error, which carries the public category and next action.

Where this goes wrong in practice

The typical bug is a dashboard that counts jobs by status string. It works for a month on one route, then a second route is added and a bucket named cancelled appears next to one named canceled. Counts drift and nobody notices.

A normalizer at the boundary fixes that, and so does a rule that no code outside it reads a raw status. Add a test that feeds one value from each vocabulary through it.

Limits

The docs do not say whether the queue-shaped field will gain values, so keep a default branch in your normalizer for any unknown string. Treat unknown as non-terminal unless terminal says otherwise.