errors.ts

packages/ninety-client/src/errors.ts

1. /**
2. * Errors carry the endpoint and page that failed. When a nightly sync breaks a
3. * year from now, the log line has to say which call died and where it was in the
4. * pagination, or whoever is on call is reading raw JSON at 6am.
5. */
7. export interface NinetyErrorContext {
8. /** e.g. "POST /todos/query" */
9. endpoint: string
10. /** 0-based internal page index, when the failure happened mid-pagination. */
11. pageIndex?: number
12. /** Ninety's response body, truncated. */
13. body?: string
14. }
16. export class NinetyError extends Error {
17. readonly status: number | undefined
18. readonly context: NinetyErrorContext
20. constructor(message: string, context: NinetyErrorContext, status?: number) {
21. const where = context.pageIndex === undefined ? context.endpoint : `${context.endpoint} (page ${context.pageIndex})`
22. super(`${message} [${where}]`)
23. this.name = 'NinetyError'
24. this.status = status
25. this.context = context
26. }
27. }
29. /**
30. * 401.
31. *
32. * Says what happened, not why (rule 1). A 401 means Ninety rejected the token;
33. * the cause is not in the response. Expiry is only one candidate (Ninety tokens
34. * expire and are shown only once at generation), and generating a replacement
35. * is not free: doing so invalidates the current token, so a wrong guess here
36. * can turn a transient failure into a real one. The message lists candidates
37. * and is actionable, because the person who reads it may not be the person who
38. * built this.
39. */
40. export class NinetyAuthError extends NinetyError {
41. constructor(context: NinetyErrorContext) {
42. super(
43. 'Ninety rejected the token (401). The response does not say why. Check, in order:\n' +
44. ' 1. Does NINETY_TOKEN match the token currently shown in Ninety? Generating a new ' +
45. 'Personal Access Token INVALIDATES the previous one, so a recent regeneration ' +
46. 'elsewhere will break a stale copy: in your shell profile, in a terminal that ' +
47. 'has not re-sourced it, or in the Worker secret.\n' +
48. ' 2. Is the token past its expiry? Ninety shows the date on the token itself.\n' +
49. ' 3. Is the account still active and still an Owner or Admin?\n' +
50. 'If all three are fine, retry; a rejection with a valid token can be transient. ' +
51. 'Regenerate only after ruling the first three out, because that invalidates whatever ' +
52. 'is currently deployed.',
53. context,
54. 401,
55. )
56. this.name = 'NinetyAuthError'
57. }
58. }
60. /**
61. * 403. Wrong plan, or the account is an Observer (Observers cannot use the API).
62. *
63. * The endpoint-specific note belongs here, where the 403 is actually known.
64. * Appended by a caller to every Ninety failure, it would put a 403's
65. * explanation beside a 429: a cause nobody observed (rule 1). The status is
66. * known here and the path is in the context, so the note is conditional on
67. * both and the caller appends nothing.
68. */
69. export class NinetyForbiddenError extends NinetyError {
70. constructor(context: NinetyErrorContext) {
71. super(
72. 'Ninety refused the request (403). Check that the account is on the Thrive plan ' +
73. 'and is not an Observer, since Observers cannot generate or use API tokens.' +
74. (context.endpoint.includes('/todos/company')
75. ? ' This endpoint is also restricted to company Owners and Admins, so a role ' +
76. 'change on the token’s account produces exactly this.'
77. : ''),
78. context,
79. 403,
80. )
81. this.name = 'NinetyForbiddenError'
82. }
83. }
85. /** 429. Surfaced only after retries are exhausted. */
86. export class NinetyRateLimitError extends NinetyError {
87. readonly retryAfterMs: number | undefined
89. constructor(context: NinetyErrorContext, retryAfterMs?: number) {
90. super(
91. `Ninety rate limit hit (429) and retries are exhausted. Documented limit is 25 req/s per user. ` +
92. `Lower NINETY_RPS.`,
93. context,
94. 429,
95. )
96. this.name = 'NinetyRateLimitError'
97. this.retryAfterMs = retryAfterMs
98. }
99. }
101. /**
102. * The response did not match the expected schema. The shapes in types.ts are
103. * verified against live responses, so this means a response no longer matches
104. * them.
105. */
106. export class NinetySchemaError extends NinetyError {
107. constructor(context: NinetyErrorContext, detail: string) {
108. super(
109. `Ninety returned a shape this client did not expect: ${detail}. ` +
110. `The assumed shapes are unverified (see docs/ARCHITECTURE.md); fix the adapter, not the caller.`,
111. context,
112. )
113. this.name = 'NinetySchemaError'
114. }
115. }