Errors

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

PermissionDeniedError

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.

SubjectNotFoundError

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.

InvalidSubjectIdError

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.

HTTP mapping

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.