---
title: Errors and rate limits
description: 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.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body, parameters, or headers.",
    "request_id": "req_...",
    "details": []
  }
}
```

## 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. |
| `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 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:

```text
ratelimit-limit
ratelimit-remaining
ratelimit-reset
retry-after
```

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](/workflows/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` |