Which Sume API errors should page an engineer: route by category
Route Sume API failures by category: fix-the-input errors go to the caller, quota to finance, queue to a retry, and only internal or unexpected 5xx to on-call.
Most Sume API errors are not incidents. The error envelope carries code, category, retryable, retry_after_seconds and next_action, so your handler can decide who should hear about a failure without parsing messages. Page on-call only for what a human on the engineering side must fix.
A routing table
The categories below come from the Sume docs' list of job error categories; the owner column is a recommendation, not Sume behavior.
| Category | Typical next action | Suggested owner |
|---|---|---|
| validation | Fix input | Caller or product team |
| auth | Check API key and workspace access | Platform team, ticket |
| quota | Add funds or lower request cost | Finance or spend owner |
| queue | Retry later with the same idempotency key | Automatic retry, alert on sustained |
| generation_unavailable | Retry later | Automatic retry |
| generation_rejected | Inspect events, fix unsupported input | Product team |
| runtime_unavailable | Retry later, not aggressively | Automatic retry, watch rate |
| internal | Inspect events, contact support with request id | On-call |
Branch on code, then status
Branch on the HTTP status first, then on code; the message is for humans and may change. A 4xx at create means nothing ran and nothing was charged, so retrying it in a loop is the expensive mistake, with a 403 insufficient_scope loop as the classic example.
Always keep the request id
Every error body includes a request id, also sent as x-sume-request-id, safe to share with support. Put it in the ticket or alert text so nobody has to reproduce the call.
Sources
Related posts
More in Developers
- Which Sume API routes need no key, and how anonymous calls are limited
GET /v1/health, /v1/catalog, /v1/openapi.json and three BGM routes need no key. Anonymous calls are limited per IP at the Free rate, reads at 4x.
- Which Sume image models accept the quality parameter?
Only five Sume image rows list quality: ChatGPT Image 2, both ChatGPT Image 2.5 ids, Ideogram V3 and Ideogram 4.5. Every other row returns 400 if you send it.
- Which Sume API should a workflow agent step call?
A workflow agent step needs a fixed recipe, a clock, or an open task. Pick Format run, Scheduled action or Agent Completion by what you know up front.
- Which Timeline warnings does the free plan call show before rendering?
Timeline plan reports gaps, tail holds, frame snaps and ignored motion, but not short sources, downgraded fades, fps resampling or soundtrack length.
Written by Sume