Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(api): document the NUL refusals and the stored-text cleanup

Yudhi Armyndharis19fbfdd0d0d4
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index d6bef77c9..dc54ed4cf 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`.
+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; `POST /api/infra/import-data` is the one exception and accepts a backup holding one. Message text, captions and contact names received from WhatsApp are stored without NUL characters.
### General Error Codes
| HTTP Status | Meaning | When |
| ----------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `400` | Bad Request | DTO validation failed, unknown body field, 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 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 |