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:

JSON

{
  "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 – An explanation of this occurrence.
• 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 these cases.
• instance – The trace id of the request, when Streaming Hub has one.
• errors – When present, the entries name what was refused. An entry’s location names the field, for example event_types/2.

​

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_idempotency_key	The X-Idempotency header is longer than 2048 bytes.	400
AUT-0006	The request carries no token.	401
AUT-0007	The token is expired, invalid, or malformed.	401
unauthorized	The request carries no trusted tenant context.	401
AUT-1020	The credential does not have the permission. The detail names the refused resource:action.	403
forbidden	The caller is authenticated but is not allowed to make this request.	403
delegated_relay_refused	A relayed partner call breaks the gateway contract, or the hub has no partner relay source. The detail is the same for each cause.	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
idempotency_outcome_unrecorded	An earlier request with this X-Idempotency key may have committed without a recorded outcome. Read the resource before you send anything again.	409
subscription_name_taken	A live subscription in your scope already holds the name that the create sends. The existing_id field names that subscription.	409
validation_error	The request carries a caller-correctable shape fault: a bad sink_kind, or an invalid endpoint, schema, or event_types value. A dashboard period that starts before the retained history also returns this code, with details that carry coverage_start and snapshot_at.	422
unknown_event_type	An event_types value has no catalog entry at the schema major the subscription receives it at. Each errors entry names one refused type and its major.	422
event_type_outside_nature	An event_types value names an event type that the delegated credential never receives.	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 operation has no probe for this subscription: ping on a subscription that is not a webhook, or verify on a pull subscription or on a queue subscription with no credential and no delegated grant to probe.	422
rate_limited	The tenant’s allowance for this read is spent. Wait the Retry-After seconds, then retry.	429

​

Server errors

---

code	Description	Status
internal_error	An infrastructure fault. Streaming Hub scrubs detail to internal error and logs the cause.	500
internal_error	Streaming Hub is still starting, and the request reached a route before the first startup success. detail is internal error. Wait the Retry-After seconds, then retry.	503
idempotency_outcome_unrecorded	The mutation may have committed, and its outcome was not recorded. Read the resource before you send anything again.	500
AUT-0033	Access Manager did not decide the request. Wait the Retry-After seconds, then retry.	503
rate_limiter_unavailable	Streaming Hub cannot check the tenant’s allowance for this read. Wait the Retry-After seconds, then retry.	503
delegated_party_unconfirmed	Streaming Hub cannot yet confirm the delegated party of this pull subscription. Wait the Retry-After seconds, then retry.	503
read_timeout	A dashboard or delivery-health read ran out of its time budget. The response has no Retry-After. Retry later.	503
dns_unavailable	The DNS lookup of the endpoint host failed during a create. Nothing was written. Retry with the same X-Idempotency key.	503
AUT-1021	Access Manager did not answer in time. Retry the request.	504
dns_timeout	The DNS lookup of the endpoint host timed out during a create. Nothing was written. Retry with the same X-Idempotency key.	504