Errors and status codes

The shared REST error handlers return application/problem+json. The following example matches the validation handler for a malformed request.

{
  "type": "/problems/request-validation-failed",
  "title": "Request validation failed",
  "status": 422,
  "detail": "The request did not satisfy the API contract.",
  "instance": "/api/v1/streams",
  "code": "request_validation_failed"
}

Use the HTTP status and stable code for program logic. Keep diagnostic detail text in appropriately protected logs. Translate errors into your application’s own user-facing messages.

Status handling

Status	Handling
400	Check request semantics, tokens, or operation-specific input.
401	Supply a valid credential or establish a new user session.
403	Check capabilities, role, organization, recent authentication, MFA, and licensed features.
404	Check the identifier and the caller’s resource access.
409	Refresh the resource or workspace context and reconcile before writing again.
413	Reduce the uploaded body to the operation’s documented size.
422	Correct field types, bounds, required fields, and cross-field combinations.
429	Respect admission limits and Retry-After when present.
503	Respect Retry-After when present and check service readiness or resource availability.

Operation pages reproduce the response table in the current OpenAPI contract. That contract still declares HTTPValidationError for many 422 responses, while the running application’s shared validation handler returns the problem envelope above. HTTP and domain errors can also add statuses beyond an operation’s declared table.

Workspace conflicts

A response containing X-EyesOnIt-Workspace-Changed: 1 requires refreshing the user’s workspace context. A stale context can produce 409, while an unavailable workspace can produce 403. Read the current principal and resolve the selected workspace before issuing new work.

Retries

Use Handle errors, retries, and background work to distinguish a safe read retry, an idempotent operation retry, and a write that requires reconciliation after a lost response.