> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Streaming Hub error list

> Look up the Streaming Hub error codes, the HTTP status each one carries, and what to correct in the request that triggered it.

**Error format**

Streaming Hub returns most errors as RFC 9457 problem details with the `application/problem+json` media type. Only a response on that media type carries the envelope below:

<CodeGroup>
  ```json JSON theme={null}
  {
    "type": "https://errors.lerian.studio/v1/not_found",
    "title": "Not Found",
    "status": 404,
    "detail": "subscription not found",
    "code": "not_found"
  }
  ```
</CodeGroup>

**Field definitions**

* **`type`** – A stable, versioned URI that identifies the problem type. Streaming Hub builds it as `https://errors.lerian.studio/v1/<code>`, and omits it for a problem it assigns no code to.
* **`title`** – A short human-readable summary, which is the HTTP status text (for example, `Not Found`).
* **`status`** – The HTTP status code, mirrored in the body.
* **`detail`** – A caller-safe explanation of this occurrence. For a `5xx` response, Streaming Hub scrubs the detail to the static string `internal error`, so no internal cause leaks.
* **`code`** – The stable, low-cardinality, machine-readable token to branch on. A request-validation fault, and a request that matches no route, arrive with this field empty. Branch on `status` in that case. Branch on `status` in that case.

## Client errors

***

| `code`                            | Description                                                                                                                                                    | Status |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `bad_request`                     | The request is malformed, or a required input is absent.                                                                                                       | 400    |
| `missing_idempotency_key`         | The request omits the required `X-Idempotency` header. Streaming Hub rejects the request before any write.                                                     | 400    |
| `invalid_error_class`             | The `error_class` filter on the dead-letter listing holds a value outside the recognized transport classes. Supply a recognized class.                         | 400    |
| `invalid_cursor`                  | The `after` cursor on the dead-letter listing is not a well-formed row identifier. Restart the listing.                                                        | 400    |
| `unauthorized`                    | Authentication failed, or the request carries no trusted tenant context. The body is the same for each cause the hub answers itself.                           | 401    |
| `forbidden`                       | The credential is valid, but the delegated scope the request presents disagrees with the scope claim on the relayed token.                                     | 403    |
| `not_found`                       | The resource is absent, soft-deleted, held by another tenant, or of a different kind. The token is the same for each of these cases.                           | 404    |
| `idempotency_conflict`            | A duplicate request is in flight, or the same `X-Idempotency` key arrived with a different request fingerprint.                                                | 409    |
| `validation_error`                | The request carries a caller-correctable shape fault: a bad `sink_kind`, or an invalid endpoint, schema, or `event_types` value.                               | 422    |
| `inline_sink_config_forbidden`    | A create request carried inline `sink_config` or `credential` material. Send a queue credential through `PUT /v1/subscriptions/{id}/credential` instead.       | 422    |
| `endpoint_blocked`                | The resolved host is blocked, private, or a metadata address, or the URL carries embedded user information. Supply a public endpoint that holds no credential. | 422    |
| `no_secret_to_rotate`             | A secret rotation targeted a subscription that holds no signing secret.                                                                                        | 422    |
| `probe_unsupported_for_sink_kind` | The sink kind has no registered probe for this operation. Sink kinds in this group verify through their own surfaces.                                          | 422    |
| `rate_limited`                    | The per-tenant inbound read throttle denied the request. Back off and retry.                                                                                   | 429    |

<Note>
  The authentication and authorization layer runs ahead of Streaming Hub. A `401` or a `403` that this layer refuses returns a plain text body, not a problem document. That body carries no `code`.
</Note>

## Server errors

***

| `code`           | Description                                                                                    | Status |
| ---------------- | ---------------------------------------------------------------------------------------------- | ------ |
| `internal_error` | An infrastructure fault. Streaming Hub scrubs `detail` to `internal error` and logs the cause. | 500    |