Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(api): name the MCP route among the NUL body-check exceptions

Yudhi Armyndharis8796a7a370c9
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 75767cfbb..ad4f11fc5 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -107,13 +107,13 @@ A few refusals add a stable machine-readable `code`, so a client can branch with
| `IMPORT_NESTED_TRANSACTION` | `409` | Another database transaction is open on the connection; retry with no other data operation in flight |
| `EXPORT_IN_PROGRESS` | `409` | A data export is in progress; retry the import after it finishes |
-Validation failures (`statusCode: 400`) return `message` as an **array** of field-level strings, with `error: "Bad Request"`, when field detail is enabled: by default outside production, or anywhere with `VALIDATION_ERROR_DETAIL=true`. Under `NODE_ENV=production` (the Docker image, compose and Helm default) detail is off unless that variable is set, and the body is only `{ "statusCode": 400, "message": "Bad Request" }`. Clients should accept `message` as either a string or an array of strings. A global `ValidationPipe` runs with `whitelist` + `forbidNonWhitelisted`, so any request-body field not declared on the DTO is rejected with `400`. A request whose path or query string contains `%00`, or whose body holds a NUL character (U+0000) in any string, is refused with `400` before the route runs. Two routes are exempt from the body check: `POST /api/infra/import-data` accepts a backup holding one and drops it from the stored text listed below, so a SQLite backup with a NUL there restores on PostgreSQL, and the ingress route (`/api/ingress/:pluginId/:instanceId/:path`) reads its body raw and hands it to its plugin as delivered. Message text, captions, chat and contact names, media types and the account's own profile name received from WhatsApp, and dead-letter errors, are stored without NUL characters.
+Validation failures (`statusCode: 400`) return `message` as an **array** of field-level strings, with `error: "Bad Request"`, when field detail is enabled: by default outside production, or anywhere with `VALIDATION_ERROR_DETAIL=true`. Under `NODE_ENV=production` (the Docker image, compose and Helm default) detail is off unless that variable is set, and the body is only `{ "statusCode": 400, "message": "Bad Request" }`. Clients should accept `message` as either a string or an array of strings. A global `ValidationPipe` runs with `whitelist` + `forbidNonWhitelisted`, so any request-body field not declared on the DTO is rejected with `400`. A request whose path or query string contains `%00`, or whose body holds a NUL character (U+0000) in any string, is refused with `400` before the route runs. The body check does not cover three routes: `POST /api/infra/import-data` accepts a backup holding one and drops it from the stored text listed below, so a SQLite backup with a NUL there restores on PostgreSQL, the ingress route (`/api/ingress/:pluginId/:instanceId/:path`) reads its body raw and hands it to its plugin as delivered, and `POST /mcp` runs outside the Nest pipe chain, so a NUL in its tool input gets an in-band `BadRequestException` tool error instead of a `400`. Message text, captions, chat and contact names, media types and the account's own profile name received from WhatsApp, and dead-letter errors, are stored without NUL characters.
### General Error Codes
| HTTP Status | Meaning | When |
| ----------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `400` | Bad Request | DTO validation failed, unknown body field, a NUL character in the URL or (outside the import and ingress routes) the body, or a business precondition not met (e.g. session not active, media over cap) |
+| `400` | Bad Request | DTO validation failed, unknown body field, a NUL character in the URL or (outside the import, ingress and MCP routes) the body, or a business precondition not met (e.g. session not active, media over cap) |
| `401` | Unauthorized | Missing/invalid/expired/revoked `X-API-Key` (or `METRICS_TOKEN` for metrics) |
| `403` | Forbidden | A valid key refused by its `allowedIps` (a blocked or undeterminable source IP) or used outside its `allowedSessions` scope, a key whose **role** is below the route's `@RequireRole` requirement, or a key with `allowedChats` that calls a route that is not chat-scoped, names a chat outside its allowlist, or sends a `quotedMessageId` outside the reply route (see Roles & Authorization); or WhatsApp itself refused an otherwise well-formed operation (for example a group write without admin rights), in which case the key is fine and each route's Errors line names the refusal; or, on an ingress `GET` verification challenge, the `verifyToken` did not match |
| `404` | Not Found | The addressed resource (session, message, webhook, batch, …) does not exist |