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	The request body, query, path, or headers are not valid.
401	unauthorized	The API key is missing or not valid.
402	insufficient_credits	The balance is not sufficient for the requested generation.
404	not_found	The resource does not exist in the current workspace.
409	job_not_completed, job_not_cancelable, or job_generation_already_started	The requested job operation is not valid for the current status.
413	payload_too_large	The request body is larger than the configured API limit.
415	unsupported_media_type	The request body was not application/json (details.received_content_type).
429	rate_limited	Too many requests in the current window.
429	queue_full	Workspace generation concurrency and queue capacity are both full.
503	provider_not_configured, provider_capacity_exceeded, or storage configuration errors	A runtime dependency is not available or is at capacity.

Request id

The API shows the Sume request id in the response body and in the response headers. When you report an issue, include the request id. Do not include API keys, signed URLs, raw media URLs, or private workspace/user ids.

Rate-limit headers

Public API responses can include:

When you receive 429, do a backoff. If retry-after is present, use it. Do not retry unsafe submit requests without an Idempotency-Key.

queue_full is different from the usual request rate limit. It means that Sume cannot accept another paid generation job for the workspace until a current queued or processing job finishes or is canceled. Full concurrency alone is not an error. While queue capacity remains, Sume accepts valid jobs as queued. Refer to Generation admission.

Provider and worker backpressure

Generation can also return capacity or runtime errors before Sume accepts the provider work.

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 not available in this runtime.	Do not retry aggressively. Examine the catalog/runtime status.
job_ledger_not_configured	Job persistence is not available.	Treat it as service unavailable.
image_not_fetchable, input_media_unreachable, or storage configuration errors	Sume could not fetch or mirror media safely.	Make sure that the input media is a public HTTPS image URL. Then retry, or contact support with the request id.

Job errors

Failed jobs show public error metadata, for example 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	Correct the input.
auth	Examine the API key and the workspace access.
quota	Add funds, or decrease the request cost.
queue	Retry later with the same idempotency key.
generation_unavailable	Retry later.
generation_rejected	Examine the events, and correct the unsupported input.
generation_timeout	Poll the status, or retry later.
runtime_unavailable	Retry later. Do not retry aggressively.
worker_timeout	Poll the status, or retry later.
internal	Examine the events, and contact support with the 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