API companion · v1

Events API: accept once, identify clearly, retry safely

Use this page to understand producer behavior. The machine-readable source remains openapi/events.yaml; this companion explains the decisions callers most often get wrong.

Audience: producer teams Auth: mTLS + audience claim Version: v1 Source: OpenAPI

Operations

POST

`/events`

Validate and accept one event. Returns 202 with the event ID and acceptance status.

GET

`/events/{id}`

Look up one event by opaque ID. Returns 200 or 404; this is not a list endpoint.

Caller conventions

Identity

Send a stable opaque id. Reusing an accepted ID must not create a second warehouse row.

Trace

Send X-Request-Id; the service echoes it on every response.

Retry

Retry only responses whose body sets retryable: true, using bounded exponential backoff.

Version

Breaking changes move to /v2. Adding an optional field is not a breaking change.

Request and response specimens

httpPOST /events
X-Request-Id: req_7f3
Content-Type: application/json

{"id":"evt_01","type":"checkout.paid"}

202 Accepted
{"id":"evt_01","status":"accepted"}

Acceptance means the event reached the current queue, not that the warehouse has already written it.

http · proposed RFC 014 behavior202 Accepted
X-Request-Id: req_7f4

{"id":"evt_02","status":"shed",
 "code":"INGEST_SHED","retryable":true}

Retry with backoff. Reuse the same event ID so idempotency and partitioning stay deterministic.

Error catalog

Stable error codes
Code	Meaning	Retry?	Caller action
`INGEST_SHED`	Selected queue unavailable	Yes	Back off and resend the same ID
`INVALID_EVENT`	Envelope failed schema validation	No	Correct the payload
`UNAUTHORIZED_PRODUCER`	Identity or audience not accepted	No	Correct service identity or audience

Known specification drift

Not shipped: OpenAPI and the current implementation still return 503 on queue overload. The 202 + INGEST_SHED specimen is proposed by RFC 014 and must not be treated as current until the source file changes.

Last companion review: 2026-08-18. The OpenAPI file wins whenever this page disagrees.