Errors and rate limits

Sume returns structured public errors. Error bodies include a request id that is safe to share with Sume support.

Common API errors

Status	Code	Meaning
400	invalid_request or bad_request	Request body, query, path, or headers are invalid.
401	unauthorized	API key is missing or invalid.
402	insufficient_credits	Balance is not sufficient for the requested generation.
404	not_found	Resource does not exist in the current workspace.
409	job_not_completed or job_not_cancelable	The requested job operation is not valid for the current status.
413	payload_too_large	Request body exceeds the configured API limit.
429	rate_limited	Too many requests in the current window.
429	queue_full	Workspace generation concurrency plus queue capacity is full.
503	provider_not_configured, provider_capacity_exceeded, or storage configuration errors	Runtime dependency is unavailable or at capacity.

Request id

The API exposes the Sume request id in the response body and response headers. Include it when reporting an issue. Do not include API keys, signed URLs, raw media URLs, or private workspace/user ids.

Rate-limit headers

Public API responses can include:

Back off when you receive 429. Use retry-after when present. Do not retry unsafe submit requests without an Idempotency-Key.

queue_full is different from ordinary request rate limiting. It means Sume cannot accept another paid generation job for the workspace until an existing queued or processing job finishes or is canceled. Concurrency being full by itself is not an error; Sume accepts valid jobs as queued while queue capacity remains. See Generation admission.

Provider and worker backpressure

Generation can also return capacity or runtime errors before provider work is accepted.

Code	Meaning	Client behavior
provider_capacity_exceeded	Sume's provider dispatch queue is full.	Retry later with the same idempotency key.
provider_not_configured	Provider execution is unavailable in this runtime.	Do not retry aggressively; check catalog/runtime status.
job_ledger_not_configured	Job persistence is unavailable.	Treat as service unavailable.
media_fetch_failed or storage configuration errors	Sume could not fetch or mirror media safely.	Check that input media is a public HTTPS image URL, then retry or contact support with the request id.

Job errors

Failed jobs expose public error metadata such as category, stage, retryability, retry-after seconds, public reason, and next action. Internal provider payloads are not public API fields.

Common job error categories include:

Category	Typical next action
validation	Fix input.
auth	Check API key and workspace access.
quota	Add funds or lower request cost.
provider_unavailable	Retry later.
provider_rejected	Inspect events and fix unsupported input.
provider_timeout	Poll status or retry later.
media_mirror_failed	Inspect events; result may not have a Sume media URL.
worker_timeout	Poll status or retry later.
internal	Inspect events and contact support with request/job id.

Status vocabulary

Object	Values
Job status	queued, processing, completed, failed, canceled
Resource status	processing, ready, failed, canceled, archived
Webhook delivery status	pending, delivering, delivered, retrying, failed, exhausted