Errors and rate limits
Public error envelopes, request ids, rate limits, and backpressure behavior.
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 workspace does not have enough credits for the request. Refer to Not enough credits. |
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. |
Not enough credits
All usage is in credits. When the workspace balance cannot cover a request,
Sume answers 402 insufficient_credits before any provider work starts:
details.required_credits is what the request needs. details.available_credits
is what the workspace has now. An organization workspace without a provisioned
wallet gets 402 organization_wallet_not_provisioned with the same details.
Upgrade the plan or buy credits, and then retry. Refer to
Billing and credits.
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. |
input_media_too_large | An input image is larger than the model accepts (reference images up to 30 MB each, at most 10 of them over 7 MB). | Send a smaller image. The same request fails the same way. |
reference_staging_failed | Sume could not stage a large reference image for the model. Nothing was generated. | 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 credits (upgrade the plan or buy credits), or send a request that uses fewer credits. |
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. |
A job whose media runtime refused Sume's own credentials fails once with public reason provider_auth_failed (category generation_unavailable, not retryable, next action contact_support). It is a Sume configuration fault, not a timeout and not your input: do not retry it. A failure that carries an HTTP status is never reported as generation_timeout.
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 |