errors

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

All errors return consistent JSON (handled by the global error handler):

• Required: error (string), statusCode (number)
• Optional: code (e.g. INVALID_CREDENTIALS), feedback (password rules), constraint (DB constraint), retryAfter (429), details (validation errors)

Security

• No sensitive data: Never expose passwords, tokens, secrets, or internal paths in error messages.
• Generic auth errors: Use InvalidCredentialsError with the same message for "user not found" and "wrong password" to prevent user enumeration.
• Stack traces: Only in development (NODE_ENV !== 'production'); never in production responses.
• Logging: Log full error details server-side; sanitize client responses.

See the security skill for timing-safe comparison and minimum-response-time rules that complement generic error messages.

Error Class Pattern

export class NotFoundError extends Error {
  readonly statusCode = 404;

  constructor(entity: string, id: string) {
    super(`${entity} with id ${id} not found`);
    this.name = 'NotFoundError';
    Object.setPrototypeOf(this, NotFoundError.prototype);
    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, NotFoundError);
    }
  }
}