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
- Crash-safe Sume submit: write the intent row and key first
If your process dies after a Sume submit but before storing the job id, a pre-written intent row and Idempotency-Key let the retry return the original job.
- Zod 4 discriminated union for Sume job and run webhooks (TypeScript)
Parse Sume job.* and format.run.terminal webhooks with one Zod 4 discriminatedUnion: typed branches, degraded runs, oversized receipts. Tested with Zod 4.
- Zod 4 toJSONSchema to Sume output_schema: nullable, not optional
z.toJSONSchema works for a Sume Format output_schema if you use nullable instead of optional. A tested table of what passes and what the validator rejects.
- Which MCP server lets Claude Code or Cursor generate video and images?
MCP servers that let Claude Code and Cursor make video and images: Sume, fal, Replicate, Runway, Higgsfield. Endpoints, sign-in, billing, setup.
Written by Sume