Errors

HTTP API errors use one shared response shape:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "category": "validation",
    "message": "Request validation failed.",
    "correlationId": "correlation-1234",
    "details": { "field": "identifier" }
  }
}

Category	Default code	Meaning
validation	VALIDATION_FAILED	Input failed validation.
authentication	AUTHENTICATION_FAILED	Authentication is missing or invalid.
authorization	AUTHORIZATION_FAILED	Authenticated caller lacks permission.
not_found	RESOURCE_NOT_FOUND	Resource does not exist or is deliberately hidden.
conflict	CONFLICT	Request conflicts with current state.
dependency_failure	DEPENDENCY_FAILURE	Required dependency failed or is unavailable.
flow_failure	FLOW_FAILURE	Telemetry flow execution failed safely.
rate_limit	RATE_LIMITED	Retry only after the response delay.
internal	INTERNAL_ERROR	Unexpected server-side failure.

Auth API status semantics are:

• 400 invalid request payload;
• 401 missing, invalid, expired, or revoked authentication;
• 403 insufficient permission, disallowed browser origin, or a required password change;
• 404 resource absent or deliberately hidden by tenant/organization scope;
• 409 protected five-second refresh race, with Retry-After: 1;
• 429 login throttle or exhausted password-check capacity, with Retry-After;
• 503 unavailable PostgreSQL dependency;
• 500 unexpected internal failure.

Bearer 401 responses include WWW-Authenticate: Bearer. Authentication responses, including errors, use Cache-Control: no-store.

details values are limited to strings, numbers, booleans, and null. They must not contain passwords, tokens, credentials, secrets, raw payloads, or data from another tenant or organization. Clients should include the response x-correlation-id when reporting a failure to support or operations.