Errors

Every non-2xx response follows a consistent JSON envelope. The HTTP status is derived from the domain exception class name by convention — no bespoke error catalog to consult.

Response format

{
  "statusCode": 404,
  "error": "ResourceNotFoundException",
  "message": "Resource not found: abc-123",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/spaces/space-1/resources/abc-123"
}

Field	Description
statusCode	HTTP status code
error	Exception class name (e.g. ResourceNotFoundException), or InternalServerError for infrastructure failures
message	Human-readable message. Generic for infrastructure failures (technical details are logged server-side, never exposed)
timestamp	ISO 8601 timestamp
path	Request URL

Status code mapping

Domain exception class names map to HTTP status via a simple suffix convention:

Suffix	HTTP status	Example
*NotFoundException	404 Not Found	ResourceNotFoundException, SpaceNotFoundException
*AlreadyExistsException	409 Conflict	SpaceAlreadyExistsException
*ConstraintException	409 Conflict	SameSpaceConstraintException
*PermissionsException	403 Forbidden	InsufficientPermissionsException
Other domain exceptions	422 Unprocessable Entity	TypeMismatchException, InvalidDateRangeException

Authentication errors follow the standard OAuth2 semantics:

Status	When
401 Unauthorized	Missing, invalid, or expired access token
403 Forbidden	Valid token but the user has no access to the requested Space, or insufficient permissions for the operation

Validation errors

Input validation failures (missing required fields, type mismatches, payload too large, etc.) return 400 Bad Request with a message describing the first failing field.

Infrastructure failures

Database connectivity issues, external service outages, and other infrastructure failures always return 500 Internal Server Error. The response body does not leak implementation details — check the generic message and retry later, or report the timestamp and path to support.