Skip to main content

API Conventions

This page covers the conventions customers should expect from the supported /api/v1 API surface.

Error envelope​

StatiBeat uses a standard JSON error envelope:

{
  "error": "invalid ID parameter"
}

The backend standardizes this shape in handlers.ErrorResponse.

Unknown JSON fields​

Request payloads reject unknown JSON fields. That is intentional, and it helps integrations fail fast when payloads drift from the supported contract.

Rate limiting​

Default rate limits in the open-source backend are deployment-configurable, but the current defaults in code are:

  • public read traffic: 100 requests per minute
  • internal-service read traffic: 600 requests per minute
  • authenticated admin write traffic: 120 write requests per minute
  • subscriber and request-access creation flows: 10 requests per minute
  • magic-token management flows: 30 requests per minute

Production deployments may override those defaults, so clients should still handle 429 responses with retry and backoff.

The Redis-backed rate limiters include Retry-After, X-RateLimit-Tier, X-RateLimit-Limit, and X-RateLimit-Window-Seconds headers. The authenticated admin write limiter is scoped per authenticated principal and route.

Retry guidance​

  • Safe GET requests can usually be retried with exponential backoff.
  • Mutating requests should only be retried when the caller can prove they are safe to repeat.
  • Treat 400 responses as request-shape or validation problems.
  • Treat 401 and 403 as auth or permission failures.
  • Treat 429 as a signal to back off.
  • Treat 5xx responses as transient service-side failures unless support guidance says otherwise.

Visibility tiers​

Operations in the generated contract carry a doc-visibility classification:

  • public
  • customer
  • private

The public docs artifact excludes private routes on purpose.