Streaming Hub error list

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:

{
  "type": "https://errors.lerian.studio/v1/not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "subscription not found",
  "code": "not_found"
}

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

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.

Server errors

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

Catalog

Subscriptions

Event Delivery

Admin

Operational

Error handling

Streaming Hub error list

Client errors

Server errors

​Client errors

​Server errors

Client errors

Server errors