qauth: Skill for Claude Code

Error Handling (QAuth)

Standards-aligned error handling for the QAuth auth-server. Throw domain errors, return a consistent JSON shape, and never leak sensitive data. Use this skill when raising/handling errors or reviewing error-handling code.

Use Domain Errors

Throw domain-specific errors from @qauth-labs/shared-errors:

// ✅ GOOD: Domain error with statusCode
import { NotFoundError, InvalidCredentialsError } from '@qauth-labs/shared-errors';

if (!user) {
  throw new NotFoundError('User', userId);
}

if (!passwordValid) {
  throw new InvalidCredentialsError(); // Generic message prevents enumeration
}

// ❌ BAD: Generic Error or ad-hoc status codes
throw new Error('User not found');
reply.code(404).send({ error: 'Not found' });

Error Response Shape

The global error handler (apps/auth-server/src/app/plugins/error-handler.ts) answers in one of two formats, chosen by the route's config.errorFormat (ADR-019 Decision 7, #513):

• problem (the default): an RFC 9457 document, application/problem+json, with type, title, status, detail, instance, a stable lower-case code and trace_id (the request id); errors[] (pointer, message) for a validation failure and for weak-password feedback under /password.
• oauth, set on the OAuth protocol endpoints only (token, authorize, introspect, revoke, register, userinfo, the wallet-facing OID4VP endpoints): { error, error_description? } and nothing else.

Which code and which OAuth error a domain error class answers is set once, in apps/auth-server/src/app/api-conventions/error-classes.ts; a new class in @qauth-labs/shared-errors needs an entry there (a test fails without one). A class a route or a server library defines with a statusCode (the SSF transmitter's, SignInRequiredError) goes in APP_ERROR_CLASSES there, with a published code for its status; a test fails without one. A route never sends an error body of its own: it throws, and the handler answers. An OAuth error class carries its token as its message and its prose in errorDescription. A refusal that several routes raise comes from one helper in the module that owns it (e.g. helpers/token-subject.ts), so it reads one way. Tests assert code (problem) or error (OAuth) and the status, never the wording.