Errors

The Wordloop Core API follows RFC 9457 (application/problem+json) for error responses. Every error carries a status (HTTP code), a title (short stable description), and an optional detail string with context. Clients and AI agents should branch on status and title — these are stable and never renumbered.

Envelope

All error responses follow this shape:

{
  "status": 404,
  "title": "Not Found",
  "detail": "No meeting with the provided id exists.",
  "instance": "/meetings/abc123"
}

Validation errors include an errors array of field-level diagnostics:

{
  "status": 400,
  "title": "Unprocessable Entity",
  "detail": "Request body did not match the schema.",
  "errors": [
    { "message": "required", "path": "body.title", "value": "" }
  ]
}

Common HTTP status codes

Status	Title	Meaning	Action
401	Unauthorized	The request lacked a valid Clerk token or session.	Re-authenticate; refresh token.
403	Forbidden	The caller is authenticated but not authorised for this resource.	Confirm role and scope. Do not retry.
404	Not Found	The resource does not exist.	Verify the identifier; check user visibility.
400	Unprocessable Entity	The request body did not match the schema.	Inspect `errors` for field-level diagnostics.
409	Conflict	An `Idempotency-Key` was reused with a different payload.	Generate a fresh key; retry.
429	Too Many Requests	Per-caller rate limit exceeded.	Back off per `Retry-After`.
504	Gateway Timeout	A downstream dependency timed out.	Retry with exponential backoff.
500	Internal Server Error	Unexpected server error; details captured in our observability.	Retry with backoff; escalate if sustained.

WebSocket error frames

Real-time errors use a custom envelope on the wire:

{
  "type": "error",
  "error": {
    "code": "SESSION_EXPIRED",
    "message": "Session token expired; reconnect with a fresh one.",
    "details": { "session_id": "sess_..." }
  }
}

Code	Meaning	Action
`SESSION_EXPIRED`	The WebSocket session token is no longer valid.	Fetch a new token; reconnect.
`RESUME_FAILED`	The server could not resume the session at the supplied sequence.	Reconnect without a resume token; rehydrate state.
`BACKPRESSURE_SHED`	Informational: the server dropped a low-priority message because the client could not keep up.	No client action required.

Errors

Errors

Envelope

Common HTTP status codes

WebSocket error frames

Further reading

On this page