Skip to main content
All public routes are fronted by the gateway and return conventional HTTP status codes. Error bodies follow FastAPI’s convention — a JSON object with a detail field:
detail is a human-readable string for client errors, or a list of field errors for request-validation failures (422).

​
Status codes

​
By surface

Authentication / admin (/admin/*)
  • 403 on a missing or wrong admin token (detail: "Invalid or missing admin token.").
  • 404 minting a token for a non-existent user id.
  • 422 minting with an invalid scope (valid: bot, tx, browser).
Meetings API (/meetings, /bots, /transcripts/*)
  • 401 on a missing or invalid X-API-Key; 403 when the key lacks the route’s scope.
  • 404 reading a transcript for a meeting that was never started.
  • POST /meetings (plan) → 409 when a non-terminal meeting already exists for that link; 422 on an unrecognizable meeting_url.
  • PATCH /meetings/{id} → 409 once the bot lifecycle owns the record (a planned meeting is only editable while it’s still planned); 409 when the new link collides with another active meeting.
  • DELETE /meetings/{id} deletes a plan before spawn or deletes transcript/recording artifacts after the lifecycle is terminal; it returns 409 while the meeting is in flight.
  • POST /bots → 409 when a bot is already active on that link (a planned record on the link is fine — the spawn claims it); 429 past your concurrency limit.
  • DELETE /bots/{platform}/{native_meeting_id} → 200 with a body ({"status":"stopping","meeting_id":…}), not 204.
  • A bot that fails to join surfaces in GET /bots/status rather than as an HTTP error on POST /bots — see Troubleshooting.
The concurrency refusal does not match this contract today. Past your concurrency limit POST /bots answers 403 with an object detail ({"code":"service_not_allowed","reason":"concurrency_limit_reached","decision_id":…}), not the documented 429 with a string. A client that treats 403 as an auth failure will stop instead of backing off — until this is fixed, branch on the reason field. Tracked as #1240.
Calendar API (/user/calendar*) — see Calendar API → Error summary. Agent API (/agent/*) — not served on the hosted service or on Kubernetes; every route answers 502 {"detail":"upstream unreachable: ConnectError"} there (vexa-platform#324). On a deployment that does run agent-api:
  • POST /invocations → 400 if the unit.v1 envelope is non-conformant.
  • POST /events → 400 if the event.v1 event is non-conformant; 422 if the event carries no plan.
  • Workspace reads → 404 (detail: "not found") if the path is absent (GET /agent/workspace/file?path=...).

​
Streaming errors

Streamed endpoints (POST /agent/chat, GET /agent/meeting/stream) open with 200 and report problems in-band as SSE frames, not as a status code:
  • rejected — a write was blocked by governance; the frame carries violations.
  • done with ok: false — the turn ended unsuccessfully.
  • On a dropped meeting stream, reconnect with the last id: echoed as Last-Event-ID to resume gaplessly.
On the hosted service and on Kubernetes both streams open 200 and close with zero bytes — no frame at all, because agent-api is not deployed. Do not read a successfully-opened stream as a healthy one (vexa-platform#324).

​
Rate limits

Two layers gate the gateway, in order:
  1. Per-IP edge throttle (pre-auth). An optional fastapi-guard edge layer caps requests per client IP before the API key is validated — so an IP flooding invalid keys, or rotating many keys from one IP to defeat the per-user limiter, is answered with 429 at the edge and never reaches admin-api. An IP that keeps offending past a threshold is auto-banned for a window. On by default everywhere — code, compose and Helm — so you opt out, not in: GUARD_ENABLED=false (or gateway.guard.enabled=false) removes the layer, GUARD_RATE_LIMIT_RPM=0 keeps it installed but stops rate limiting. See Configuration → Gateway edge protection.
  2. Per-user limiter (post-auth). A token-bucket limiter keyed by user id fires after the key is resolved — it catches one token driving too much traffic across many IPs. ON by default: a bucket of GATEWAY_RATE_LIMIT_BURST (120) tokens refilled at GATEWAY_RATE_LIMIT_RPS (40)/s, off only when GATEWAY_RATE_LIMIT_DISABLED is set. See Configuration.
A throttled request returns 429 with a Retry-After header (seconds) — honor it before retrying. Beyond rate limits, throughput is bounded by your own infrastructure and per-user concurrency (max_concurrent_bots, set when the user is created). The hosted service additionally applies plan-based limits.