From f1ebe1c8115517337c236cf5ab53e2b68dd20ac2 Mon Sep 17 00:00:00 2001 From: Kirill Mokevnin Date: Sun, 15 Nov 2026 22:35:25 -0500 Subject: [PATCH] docs(api): say that a request body refuses a property it does not declare A request body of the API is a closed object at every depth: a property it does not declare is a 400 whose `errors` names the property's path, not a field silently ignored. The maps whose keys are the caller's stay open, and so do responses, which a later release may add properties to. Co-Authored-By: Claude Opus 5.5 --- src/content/docs/docs/guide/api.md | 35 ++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/src/content/docs/docs/guide/api.md b/src/content/docs/docs/guide/api.md index ee285c7..c701903 100644 --- a/src/content/docs/docs/guide/api.md +++ b/src/content/docs/docs/guide/api.md @@ -117,15 +117,32 @@ Errors are [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) `application/probl `status` and `title` are always present, and `detail` for client errors. Server errors (`5xx`) carry no detail; quote the `X-Request-Id` response header when you report one. -| Status | Meaning | -| ------ | -------------------------------------------------------------------- | -| `400` | The request could not be parsed. | -| `401` | The token is missing, invalid, revoked or expired. | -| `403` | The token lacks the required scope. | -| `404` | The resource does not exist in this workspace. | -| `413` | The body is larger than the configured limit. | -| `409` | A request with the same `Idempotency-Key` is still in flight. | -| `422` | Validation failed, or a reference points at another workspace's row. | +| Status | Meaning | +| ------ | --------------------------------------------------------------------- | +| `400` | The request could not be parsed, or its body has an unknown property. | +| `401` | The token is missing, invalid, revoked or expired. | +| `403` | The token lacks the required scope. | +| `404` | The resource does not exist in this workspace. | +| `413` | The body is larger than the configured limit. | +| `409` | A request with the same `Idempotency-Key` is still in flight. | +| `422` | Validation failed, or a reference points at another workspace's row. | + +A request body is a closed object: a property the API does not declare, at any depth, is refused +with `400` instead of being ignored. A misspelt optional field (`segment_id` for `segmentId`) never +goes through as if it had been left out. `errors` names the property by its path: + +```json +{ + "status": 400, + "title": "Bad Request", + "detail": "…", + "errors": { "content.subjct": ["unknown property: the contract does not declare it"] } +} +``` + +The maps whose keys are yours stay open: a Contact's `customFields`, an Event's `properties` and an +email's `variables` take any key. Responses stay open too: a later release may add a property to a +response, so ignore the ones you do not know. ## Idempotent sends