Skip to content

Commit c43c89e

Browse files
committed
docs(wire-format): note that service-mounted routes answer in the declared envelope (#3675)
`wire-format.mdx` §7 describes the flat `{ error, code }` envelope, which is what the kernel REST server emits for `/api/v1/data/*`. With the storage and i18n routes moved to the declared `BaseResponse` shape, a reader following §7 would look for `body.code` on those routes and find nothing. Says which envelope belongs to which surface, and that SDK callers need not branch because `ObjectStackClient` normalizes both. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent bc2ab0e commit c43c89e

1 file changed

Lines changed: 21 additions & 0 deletions

File tree

content/docs/api/wire-format.mdx

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -384,6 +384,27 @@ Returned when an `If-Match` / `expectedVersion` token no longer matches the stor
384384
**Error Codes:** See the [Error Catalog](/docs/api/error-catalog) for the complete list of error codes and their meanings.
385385
</Callout>
386386

387+
### Service-mounted routes use the declared envelope
388+
389+
The flat envelope above is what the kernel REST server emits for `/api/v1/data/*`.
390+
Routes mounted directly by a service plugin — `/api/v1/storage/*` and
391+
`/api/v1/i18n/*` — instead return the `BaseResponse` shape their contract
392+
declares, with the code **inside** the error object:
393+
394+
```json
395+
{
396+
"success": false,
397+
"error": {
398+
"code": "ATTACHMENT_DOWNLOAD_DENIED",
399+
"message": "You do not have access to a record this file is attached to"
400+
}
401+
}
402+
```
403+
404+
Read `body.error.code`, not `body.code`, on these routes. `ObjectStackClient`
405+
normalizes both — `error.code` and `error.message` are populated whichever
406+
envelope the server used — so SDK callers do not need to branch.
407+
387408
---
388409

389410
## 8. Batch Operations

0 commit comments

Comments
 (0)