Errors

Every error response uses the same JSON envelope:

{
  "error": {
    "code": "invalid_parameter",
    "message": "min_divergence must be between 0 and 100.",
    "details": { "parameter": "min_divergence", "received": "150" }
  }
}

code is a stable machine-readable slug. message is human-readable. details is optional and route-specific.

Status codes

Code	When
200	OK
304	`If-None-Match` matched; body is empty
400	Invalid parameter (bad type, out of range, unknown enum value, etc.)
401	Missing or invalid token on an archive-gated route
404	Resource not found
429	Rate limit exceeded. See `Retry-After` header
500	Unexpected server error. Safe to retry with backoff
501	Endpoint is specced but not implemented (e.g. webhooks)

Error codes

Code	HTTP	Meaning
`invalid_parameter`	400	A query/path parameter failed validation
`invalid_cursor`	400	Cursor is malformed or expired
`token_required`	401	This window requires a Bearer token
`token_invalid`	401	Token is unknown or revoked
`not_found`	404	Event, outlet, or category does not exist
`rate_limited`	429	Limit exceeded for this key
`not_implemented`	501	Endpoint reserved for a future release
`internal_error`	500	Something broke. Include `X-Request-Id` in your bug report

Retry guidance

429: wait the number of seconds in Retry-After, then retry once.
500: exponential backoff starting at 1 second, up to 3 retries.
Any 4xx other than 429: do not retry. Fix the request.