git.stella-ops.org/docs/api/gateway/exception-events.md

Exception Events Gateway Contract (draft v0.1)

Scope: stream exception workflow events (exception.*) for Console activity feeds and Notify integrations.

Security / headers

• Authorization: Bearer <token> (or DPoP where configured)
• X-Stella-Tenant: <tenantId> (required; see docs/api/gateway/tenant-auth.md)
• X-Stella-Project: <projectId> (optional)
• Scopes: exception:read

Endpoint

• GET /exceptions/events — Server-Sent Events (SSE) stream.
  • Query params: tenant, traceId, projectId (optional)
  • Response: text/event-stream

Event types

• exception.created
• exception.updated
• exception.status_changed
• exception.deleted

Rate limits (proposal)

• Max 1 active SSE connection per browser session.
• Heartbeat every 30s; server closes idle connections after 60s without reads.
• When rate limited: 429 with Retry-After.

Notify integration

Gateways SHOULD forward these events to Notify where configured:

• exception.status_changed → notify.event with severity derived from exception severity and status.
• All events include traceId for audit correlation.

Samples

• docs/api/gateway/samples/exception-events.ndjson