Skip to content

Commit 3018f17

Browse files
claudeclaude
committed
docs(references): regenerate the API reference for the #3842 spec changes
`content/docs/references/` is generated from `packages/spec` by `scripts/build-docs.ts` and is gated by `check:docs`. The spec edits in the parent commit — `ApiError.httpStatus`, two new `StandardErrorCode` members, and `DispatcherErrorCode`/`DispatcherErrorResponseSchema` — left 12 reference pages stale. Regenerated with `gen:schema && gen:docs`; no hand edits. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018u8vDQLWPJxBWQESznDpSj
1 parent 170bf22 commit 3018f17

12 files changed

Lines changed: 101 additions & 82 deletions

File tree

‎content/docs/references/api/analytics.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ const result = AnalyticsEndpoint.parse(data);
4545
| Property | Type | Required | Description |
4646
| :--- | :--- | :--- | :--- |
4747
| **success** | `boolean` | ✅ | Operation success status |
48-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
48+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
4949
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
5050
| **data** | `{ cubes: { name: string; title?: string; description?: string; sql: string; … }[] }` | ✅ | |
5151

@@ -72,7 +72,7 @@ const result = AnalyticsEndpoint.parse(data);
7272
| Property | Type | Required | Description |
7373
| :--- | :--- | :--- | :--- |
7474
| **success** | `boolean` | ✅ | Operation success status |
75-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
75+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
7676
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
7777
| **data** | `{ rows: Record<string, any>[]; fields: { name: string; type: string }[]; sql?: string }` | ✅ | |
7878

@@ -86,7 +86,7 @@ const result = AnalyticsEndpoint.parse(data);
8686
| Property | Type | Required | Description |
8787
| :--- | :--- | :--- | :--- |
8888
| **success** | `boolean` | ✅ | Operation success status |
89-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
89+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
9090
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
9191
| **data** | `{ sql: string; params: any[] }` | ✅ | |
9292

‎content/docs/references/api/auth.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ const result = AuthProvider.parse(data);
102102
| Property | Type | Required | Description |
103103
| :--- | :--- | :--- | :--- |
104104
| **success** | `boolean` | ✅ | Operation success status |
105-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
105+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
106106
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
107107
| **data** | `{ session: object; user: object; token?: string }` | ✅ | |
108108

@@ -138,7 +138,7 @@ const result = AuthProvider.parse(data);
138138
| Property | Type | Required | Description |
139139
| :--- | :--- | :--- | :--- |
140140
| **success** | `boolean` | ✅ | Operation success status |
141-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
141+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
142142
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
143143
| **data** | `{ id: string; email: string; emailVerified: boolean; name: string; … }` | ✅ | |
144144

‎content/docs/references/api/automation-api.mdx‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ const result = AutomationApiErrorCode.parse(data);
129129
| Property | Type | Required | Description |
130130
| :--- | :--- | :--- | :--- |
131131
| **success** | `boolean` | ✅ | Operation success status |
132-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
132+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
133133
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
134134
| **data** | `{ name: string; label: string; description?: string; successMessage?: string; … }` | ✅ | The created flow definition |
135135

@@ -154,7 +154,7 @@ const result = AutomationApiErrorCode.parse(data);
154154
| Property | Type | Required | Description |
155155
| :--- | :--- | :--- | :--- |
156156
| **success** | `boolean` | ✅ | Operation success status |
157-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
157+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
158158
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
159159
| **data** | `{ name: string; deleted: boolean }` | ✅ | |
160160

@@ -197,7 +197,7 @@ const result = AutomationApiErrorCode.parse(data);
197197
| Property | Type | Required | Description |
198198
| :--- | :--- | :--- | :--- |
199199
| **success** | `boolean` | ✅ | Operation success status |
200-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
200+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
201201
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
202202
| **data** | `{ name: string; label: string; description?: string; successMessage?: string; … }` | ✅ | Full flow definition |
203203

@@ -223,7 +223,7 @@ const result = AutomationApiErrorCode.parse(data);
223223
| Property | Type | Required | Description |
224224
| :--- | :--- | :--- | :--- |
225225
| **success** | `boolean` | ✅ | Operation success status |
226-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
226+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
227227
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
228228
| **data** | `{ id: string; flowName: string; flowVersion?: integer; status: Enum<'pending' \| 'running' \| 'paused' \| 'completed' \| 'failed' \| 'cancelled' \| 'timed_out' \| 'retrying'>; … }` | ✅ | Full execution log with step details |
229229

@@ -251,7 +251,7 @@ const result = AutomationApiErrorCode.parse(data);
251251
| Property | Type | Required | Description |
252252
| :--- | :--- | :--- | :--- |
253253
| **success** | `boolean` | ✅ | Operation success status |
254-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
254+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
255255
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
256256
| **data** | `{ flows: { name: string; label: string; type: string; status: string; … }[]; total?: integer; nextCursor?: string; hasMore: boolean }` | ✅ | |
257257

@@ -279,7 +279,7 @@ const result = AutomationApiErrorCode.parse(data);
279279
| Property | Type | Required | Description |
280280
| :--- | :--- | :--- | :--- |
281281
| **success** | `boolean` | ✅ | Operation success status |
282-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
282+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
283283
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
284284
| **data** | `{ runs: { id: string; flowName: string; flowVersion?: integer; status: Enum<'pending' \| 'running' \| 'paused' \| 'completed' \| 'failed' \| 'cancelled' \| 'timed_out' \| 'retrying'>; … }[]; total?: integer; nextCursor?: string; hasMore: boolean }` | ✅ | |
285285

@@ -305,7 +305,7 @@ const result = AutomationApiErrorCode.parse(data);
305305
| Property | Type | Required | Description |
306306
| :--- | :--- | :--- | :--- |
307307
| **success** | `boolean` | ✅ | Operation success status |
308-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
308+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
309309
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
310310
| **data** | `{ name: string; enabled: boolean }` | ✅ | |
311311

@@ -335,7 +335,7 @@ const result = AutomationApiErrorCode.parse(data);
335335
| Property | Type | Required | Description |
336336
| :--- | :--- | :--- | :--- |
337337
| **success** | `boolean` | ✅ | Operation success status |
338-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
338+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
339339
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
340340
| **data** | `{ success: boolean; output?: any; error?: string; durationMs?: number }` | ✅ | |
341341

@@ -361,7 +361,7 @@ const result = AutomationApiErrorCode.parse(data);
361361
| Property | Type | Required | Description |
362362
| :--- | :--- | :--- | :--- |
363363
| **success** | `boolean` | ✅ | Operation success status |
364-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
364+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
365365
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
366366
| **data** | `{ name: string; label: string; description?: string; successMessage?: string; … }` | ✅ | The updated flow definition |
367367

‎content/docs/references/api/batch.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ const result = BatchConfig.parse(data);
6060
| :--- | :--- | :--- | :--- |
6161
| **id** | `string` | optional | Record ID if operation succeeded |
6262
| **success** | `boolean` | ✅ | Whether this record was processed successfully |
63-
| **errors** | `{ code: string; message: string; category?: string; details?: any; … }[]` | optional | Array of errors if operation failed |
63+
| **errors** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }[]` | optional | Array of errors if operation failed |
6464
| **data** | `Record<string, any>` | optional | Full record data (if returnRecords=true) |
6565
| **index** | `number` | optional | Index of the record in the request array |
6666
| **droppedFields** | `{ object: string; fields: string[]; reason: Enum<'readonly' \| 'readonly_when'> }[]` | optional | Write-observability (#3407/#3431/#3455): caller-supplied fields LEGALLY stripped from THIS row before it was written — static `readonly` (#2948) / TRUE `readonlyWhen` (#3042) on update, or the #3043 create-ingress strip. Per-row because a batch can drop different fields on different rows (`readonlyWhen` is record-state-dependent). Present ONLY when ≥1 field was dropped for this row; the row still succeeded (success unchanged). A single response header cannot express per-row drops, so this body field is the canonical bulk channel — REST does not emit `X-ObjectStack-Dropped-Fields` for batches. Optional — omit-when-empty keeps the shape backward-compatible. |
@@ -127,13 +127,13 @@ const result = BatchConfig.parse(data);
127127
| Property | Type | Required | Description |
128128
| :--- | :--- | :--- | :--- |
129129
| **success** | `boolean` | ✅ | Operation success status |
130-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
130+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
131131
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
132132
| **operation** | `Enum<'create' \| 'update' \| 'upsert' \| 'delete'>` | optional | Operation type that was performed |
133133
| **total** | `number` | ✅ | Total number of records in the batch |
134134
| **succeeded** | `number` | ✅ | Number of records that succeeded |
135135
| **failed** | `number` | ✅ | Number of records that failed |
136-
| **results** | `{ id?: string; success: boolean; errors?: { code: string; message: string; category?: string; details?: any; … }[]; data?: Record<string, any>; … }[]` | ✅ | Detailed results for each record |
136+
| **results** | `{ id?: string; success: boolean; errors?: { code: string; message: string; category?: string; httpStatus?: integer; … }[]; data?: Record<string, any>; … }[]` | ✅ | Detailed results for each record |
137137

138138

139139
---

‎content/docs/references/api/contract.mdx‎

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,23 @@ description: Contract protocol schemas
55

66
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
77

8-
Standard Create Request
8+
The numeric HTTP status, when a producer chooses to mirror it into the body.
9+
10+
Declared (#3842) because the runtime dispatcher had nowhere to put it and
11+
12+
used `code` — the semantic slot above — instead, handing callers `403` where
13+
14+
the contract promises a string and forcing the real code into `details`.
15+
16+
`EnhancedApiErrorSchema.httpStatus` set the precedent; this is the same
17+
18+
field on the base envelope.
19+
20+
Optional and redundant on purpose: the response status is authoritative, so
21+
22+
a producer that emits only the semantic `code` is fully conformant. Callers
23+
24+
should branch on `code`, not on this.
925

1026
<Callout type="info">
1127
**Source:** `packages/spec/src/api/contract.zod.ts`
@@ -32,6 +48,7 @@ const result = ApiError.parse(data);
3248
| **code** | `string` | ✅ | Error code (e.g. validation_error) |
3349
| **message** | `string` | ✅ | Readable error message |
3450
| **category** | `string` | optional | Error category (e.g. validation, authorization) |
51+
| **httpStatus** | `integer` | optional | HTTP status of the response carrying this error |
3552
| **details** | `any` | optional | Additional error context (e.g. field validation errors) |
3653
| **requestId** | `string` | optional | Request ID for tracking |
3754

@@ -45,7 +62,7 @@ const result = ApiError.parse(data);
4562
| Property | Type | Required | Description |
4663
| :--- | :--- | :--- | :--- |
4764
| **success** | `boolean` | ✅ | Operation success status |
48-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
65+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
4966
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
5067

5168

@@ -84,9 +101,9 @@ const result = ApiError.parse(data);
84101
| Property | Type | Required | Description |
85102
| :--- | :--- | :--- | :--- |
86103
| **success** | `boolean` | ✅ | Operation success status |
87-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
104+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
88105
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
89-
| **data** | `{ id?: string; success: boolean; errors?: { code: string; message: string; category?: string; details?: any; … }[]; index?: number; … }[]` | ✅ | Results for each item in the batch |
106+
| **data** | `{ id?: string; success: boolean; errors?: { code: string; message: string; category?: string; httpStatus?: integer; … }[]; index?: number; … }[]` | ✅ | Results for each item in the batch |
90107

91108

92109
---
@@ -126,7 +143,7 @@ const result = ApiError.parse(data);
126143
| Property | Type | Required | Description |
127144
| :--- | :--- | :--- | :--- |
128145
| **success** | `boolean` | ✅ | Operation success status |
129-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
146+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
130147
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
131148
| **id** | `string` | ✅ | ID of the deleted record |
132149

@@ -177,7 +194,7 @@ const result = ApiError.parse(data);
177194
| Property | Type | Required | Description |
178195
| :--- | :--- | :--- | :--- |
179196
| **success** | `boolean` | ✅ | Operation success status |
180-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
197+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
181198
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
182199
| **data** | `Record<string, any>[]` | ✅ | Array of matching records |
183200
| **pagination** | `{ total?: number; limit?: number; offset?: number; cursor?: string; … }` | ✅ | Pagination info |
@@ -193,7 +210,7 @@ const result = ApiError.parse(data);
193210
| :--- | :--- | :--- | :--- |
194211
| **id** | `string` | optional | Record ID if processed |
195212
| **success** | `boolean` | ✅ | |
196-
| **errors** | `{ code: string; message: string; category?: string; details?: any; … }[]` | optional | |
213+
| **errors** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }[]` | optional | |
197214
| **index** | `number` | optional | Index in original request |
198215
| **data** | `any` | optional | Result data (e.g. created record) |
199216

@@ -226,7 +243,7 @@ const result = ApiError.parse(data);
226243
| Property | Type | Required | Description |
227244
| :--- | :--- | :--- | :--- |
228245
| **success** | `boolean` | ✅ | Operation success status |
229-
| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false |
246+
| **error** | `{ code: string; message: string; category?: string; httpStatus?: integer; … }` | optional | Error details if success is false |
230247
| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata |
231248
| **data** | `Record<string, any>` | ✅ | The requested or modified record |
232249

‎content/docs/references/api/dispatcher.mdx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -60,14 +60,14 @@ const result = DispatcherConfig.parse(data);
6060

6161
## DispatcherErrorCode
6262

63-
404 = route not found, 405 = method not allowed, 501 = not implemented (stub), 503 = service unavailable
63+
Route-resolution failure mode emitted in `error.code`
6464

6565
### Allowed Values
6666

67-
* `404`
68-
* `405`
69-
* `501`
70-
* `503`
67+
* `ROUTE_NOT_FOUND`
68+
* `METHOD_NOT_ALLOWED`
69+
* `NOT_IMPLEMENTED`
70+
* `SERVICE_UNAVAILABLE`
7171

7272

7373
---
@@ -79,7 +79,7 @@ const result = DispatcherConfig.parse(data);
7979
| Property | Type | Required | Description |
8080
| :--- | :--- | :--- | :--- |
8181
| **success** | `'false'` | ✅ | |
82-
| **error** | `{ code: integer; message: string; type?: Enum<'ROUTE_NOT_FOUND' \| 'METHOD_NOT_ALLOWED' \| 'NOT_IMPLEMENTED' \| 'SERVICE_UNAVAILABLE'>; route?: string; … }` | ✅ | |
82+
| **error** | `{ code: string; message: string; httpStatus?: integer; route?: string; … }` | ✅ | |
8383

8484

8585
---

0 commit comments

Comments
 (0)