errors.ts · Source

errors.tsapps/api/src/common/errors.tsraw ← common4,904 B← Back to the app
1/**
2 * Typed application error. Every non-2xx response is produced from an
3 * ApiError (directly or by mapping a known exception) into the canonical
4 * envelope { error: { code, message, details?, requestId } }.
5 */
6 
7export type ErrorCode =
8  | "VALIDATION_ERROR"
9  | "UNAUTHORIZED"
10  | "INVALID_TOKEN"
11  | "TOKEN_EXPIRED"
12  | "FORBIDDEN"
13  | "SCOPE_DENIED"
14  | "NOT_FOUND"
15  | "CONFLICT"
16  | "PRECONDITION_FAILED"
17  | "GONE"
18  | "UNPROCESSABLE_ENTITY"
19  | "RATE_LIMITED"
20  | "PAYLOAD_TOO_LARGE"
21  | "QUOTA_EXCEEDED"
22  | "AI_BUDGET_EXCEEDED"
23  | "AI_NOT_CONFIGURED"
24  | "SEARCH_UNAVAILABLE"
25  | "STORAGE_ERROR"
26  // File pipeline (Phase 9 — docs/tasks/phase-09-files.md TASK-0101/0102/0104).
27  | "FILE_TOO_LARGE"
28  | "MIME_MISMATCH"
29  | "UPLOAD_INCOMPLETE"
30  | "UPLOAD_EXPIRED"
31  | "FILE_QUARANTINED"
32  | "SERVICE_UNAVAILABLE"
33  | "NOT_IMPLEMENTED"
34  | "UNSUPPORTED_MEDIA_TYPE" // Phase 10 (TASK-0108): the public submit's 415 content-type guard
35  // Automation (Phase 11 — docs/tasks/phase-11-automation.md TASK-0110):
36  // incoming webhook signature verification failures (401, code carries the
37  // reason so clients can debug without leaking which check failed first).
38  | "WEBHOOK_SIGNATURE_INVALID"
39  | "WEBHOOK_TIMESTAMP_STALE"
40  | "WEBHOOK_RATE_LIMITED" // 429 — per-webhookId 60/min (Redis window)
41  | "WEBHOOK_REPLAY_DETECTED" // 401 — TASK-0130: same t+body-hash nonce seen within the 10-min window
42  // TASK-0134 — formula-engine DoS guard (docs/api/authentication.md §9.1):
43  // a syntactically valid formula that exceeds the 100k-op budget or the
44  // 50 ms wall-clock budget. 422 UNPROCESSABLE_ENTITY (syntactically valid,
45  // too much work). Distinct from the save-time PARSE/TYPE/UNKNOWN_FUNCTION
46  // codes (400) and from RUNTIME (null-prop / output-size) which stay 400.
47  | "FORMULA_TIMEOUT"
48  // TASK-0129 — RFC 6749 OAuth2 token-endpoint error codes (docs/api/
49  // authentication.md §8.2). Carried in the canonical envelope's `code` field
50  // (the app-wide pattern). The RFC's flat `{error, error_description}` body
51  // is a recorded divergence (C-13.7) — the envelope is superset-safe for
52  // clients that read `error.code` / `error.message`.
53  | "INVALID_GRANT"
54  | "INVALID_CLIENT"
55  | "INVALID_SCOPE"
56  | "INTERNAL_ERROR";
57 
58export interface ErrorDetail {
59  field?: string;
60  issue?: string;
61  reason?: string;
62  received?: unknown;
63  retryAfterSeconds?: number;
64  [key: string]: unknown;
65}
66 
67export class ApiError extends Error {
68  constructor(
69    public readonly code: ErrorCode,
70    public readonly httpStatus: number,
71    message: string,
72    public readonly details?: ErrorDetail[]
73  ) {
74    super(message);
75    this.name = "ApiError";
76  }
77 
78  static validation(message = "Request validation failed.", details?: ErrorDetail[]): ApiError {
79    return new ApiError("VALIDATION_ERROR", 400, message, details);
80  }
81  static unauthorized(message = "Authentication required.", details?: ErrorDetail[]): ApiError {
82    return new ApiError("UNAUTHORIZED", 401, message, details);
83  }
84  static forbidden(message = "Permission denied.", details?: ErrorDetail[]): ApiError {
85    return new ApiError("FORBIDDEN", 403, message, details);
86  }
87  static notFound(message = "Resource not found."): ApiError {
88    return new ApiError("NOT_FOUND", 404, message);
89  }
90  static conflict(message = "Resource conflict.", details?: ErrorDetail[]): ApiError {
91    return new ApiError("CONFLICT", 409, message, details);
92  }
93  /** 422 — structurally valid request that fails domain validation
94   * (TASK-0110: per-type trigger/condition/action config failures, cron
95   * matrix, status machine, sub-resource caps). */
96  static unprocessable(message = "Request is not processable.", details?: ErrorDetail[]): ApiError {
97    return new ApiError("UNPROCESSABLE_ENTITY", 422, message, details);
98  }
99  static webhookSignatureInvalid(message = "Invalid webhook signature."): ApiError {
100    return new ApiError("WEBHOOK_SIGNATURE_INVALID", 401, message, [{ reason: "signature_invalid" }]);
101  }
102  static webhookTimestampStale(message = "Webhook timestamp outside the ±5 minute window."): ApiError {
103    return new ApiError("WEBHOOK_TIMESTAMP_STALE", 401, message, [{ reason: "timestamp_expired" }]);
104  }
105  static webhookRateLimited(message = "Webhook rate limit exceeded (60/min).", retryAfterSeconds = 60): ApiError {
106    return new ApiError("WEBHOOK_RATE_LIMITED", 429, message, [{ retryAfterSeconds }]);
107  }
108  /** TASK-0130: the same signature+timestamp+body was already accepted
109   *  within the replay window (Redis nonce, 10 min TTL). */
110  static webhookReplayDetected(message = "Webhook replay detected (duplicate signature nonce)."): ApiError {
111    return new ApiError("WEBHOOK_REPLAY_DETECTED", 401, message, [{ reason: "replay_detected" }]);
112  }
113  static internal(message = "Internal server error."): ApiError {
114    return new ApiError("INTERNAL_ERROR", 500, message);
115  }
116}
117