Skip to content

Errors

The vperms package defines four errors. Integrations map them to HTTP status codes consistently.

class PermissionDeniedError extends Error {
readonly permission: string;
readonly status: 403;
}

Thrown when a caller is not allowed to perform an operation — most notably by exportResolvedSubject when the caller cannot read the target subject’s permissions.

class SubjectNotFoundError extends Error {
readonly subjectId: string;
readonly status: 404;
}

Thrown when a subject has no record, for example from resolvePermissions or when exporting permissions for a non-existent subject.

class InvalidSubjectIdError extends Error {
readonly subjectId: string;
readonly status: 400;
}

Thrown when a subject id fails schema validation, for example when a malformed id is requested from the export endpoint.

class SubjectResolutionError extends Error {}

Thrown when a value passed as a subject cannot be resolved: it is neither an explicit SubjectRef nor a SubjectResolver, or its getSubjectId() / getSubjectType() return invalid values. Unlike the errors above it is a programming error rather than an HTTP-mapped condition; integrations surface it as a 500. See Subjects.

Error Status Export/served by
InvalidSubjectIdError 400 Express/Hono/Nest/Next export routes
PermissionDeniedError 403 All request integrations
SubjectNotFoundError 404 All request integrations
  • Express — 403/404 via res.sendStatus, 400 as JSON { error }.
  • Hono — 403/404 via c.body(null, ...), 400 as c.json({ error }).
  • Nest — guard denials become Nest’s own 403; the export controller maps the errors above.
  • Next.js — NextResponse.json for success, the same status codes for failures.

Client-side, VPermsHttpError wraps any non-2xx response from fetchResolvedSubject, exposing status and url.