Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(api): document the over-allowance 400 on group create and add

Yudhi Armyndharis0020105b3903
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 9dd2bf9f8..f26fada77 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -2889,7 +2889,7 @@ Returns the created `Group` directly (raw).
}
```
-**Errors:** `400` validation (missing/empty `name` or `participants`, or any non-DTO field) / session not started, or a participant does not name an individual (phone, `<phone>@c.us` or `<lid>@lid`) · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, or WhatsApp refused the create · `409` conflict or engine not ready (retryable) · `429` `SEND_PACING_LIMITED` when send pacing is enabled (cold-reachout cap, see Send pacing) · `501` not supported on the active engine · `503` WhatsApp rate-limited the create on Baileys (code 429; nothing was created, so a retry is safe; a timed-out create is not answered `503`)
+**Errors:** `400` validation (missing/empty `name` or `participants`, or any non-DTO field) / session not started, or a participant does not name an individual (phone, `<phone>@c.us` or `<lid>@lid`), or (send pacing on) the request names more new contacts than the whole day's cold-reachout allowance (no `retryAfterSeconds`; split the batch, see Send pacing) · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, or WhatsApp refused the create · `409` conflict or engine not ready (retryable) · `429` `SEND_PACING_LIMITED` when send pacing is enabled (cold-reachout cap reached for today, see Send pacing) · `501` not supported on the active engine · `503` WhatsApp rate-limited the create on Baileys (code 429; nothing was created, so a retry is safe; a timed-out create is not answered `503`)
#### POST /api/sessions/:sessionId/groups/:groupId/participants
@@ -2931,7 +2931,7 @@ Status is forced to `200` via `@HttpCode(HttpStatus.OK)` (overriding the POST de
Each entry is a `ParticipantOperationResult`: `id` (the participant the outcome belongs to), `success` (true only when the engine confirmed the change for that participant), and the optional engine-reported `status`/`message` (e.g. `200` ok, `403` invite-only/not-admin, `404` not registered, `409` already a member). Engines that only confirm the batch as a whole report one success entry per requested participant.
-**Errors:** `400` validation / session not started, or a participant does not name an individual (phone, `<phone>@c.us` or `<lid>@lid`) · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, or WhatsApp refused every listed participant (a partial refusal still returns `200`) · `404` group not found · `409` conflict or engine not ready (retryable) · `429` `SEND_PACING_LIMITED` when send pacing is enabled (cold-reachout cap, see Send pacing) · `503` session not ready or dependency unavailable (retryable)
+**Errors:** `400` validation / session not started, or a participant does not name an individual (phone, `<phone>@c.us` or `<lid>@lid`), or (send pacing on) the request names more new contacts than the whole day's cold-reachout allowance (no `retryAfterSeconds`; split the batch, see Send pacing) · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, or WhatsApp refused every listed participant (a partial refusal still returns `200`) · `404` group not found · `409` conflict or engine not ready (retryable) · `429` `SEND_PACING_LIMITED` when send pacing is enabled (cold-reachout cap reached for today, see Send pacing) · `503` session not ready or dependency unavailable (retryable)
#### DELETE /api/sessions/:sessionId/groups/:groupId/participants
diff --git a/src/modules/group/group.controller.spec.ts b/src/modules/group/group.controller.spec.ts
index 83e86cc30..1aec6c2f1 100644
--- a/src/modules/group/group.controller.spec.ts
+++ b/src/modules/group/group.controller.spec.ts
@@ -171,4 +171,13 @@ describe('GroupController OpenAPI responses', () => {
it('declares the rate-limited 503 on group creation', () => {
expect(responsesOf('create')['503']?.description).toContain('429');
});
+
+ // A batch larger than a whole day's cold-reachout allowance is refused 400 without a retry hint.
+ it.each(['create', 'addParticipants'])('%s describes the over-allowance 400', name => {
+ expect(responsesOf(name)['400']?.description).toContain('cold-reachout allowance');
+ });
+
+ it.each(['removeParticipants', 'promoteParticipants', 'demoteParticipants'])('%s keeps the unpaced 400', name => {
+ expect(responsesOf(name)['400']?.description).not.toContain('cold-reachout');
+ });
});
diff --git a/src/modules/group/group.controller.ts b/src/modules/group/group.controller.ts
index ec380cf21..3e414884b 100644
--- a/src/modules/group/group.controller.ts
+++ b/src/modules/group/group.controller.ts
@@ -60,6 +60,12 @@ const PARTICIPANT_ID_400 =
'A participant does not name an individual. Pass a phone number, `<phone>@c.us` or `<lid>@lid`; ' +
'a group id or free text is rejected.';
+// Only the two routes that add people to a group are paced; remove, promote and demote are not.
+const PACED_PARTICIPANT_400 =
+ PARTICIPANT_ID_400 +
+ ' With send pacing on, also answered (without `retryAfterSeconds`) when the request names more new ' +
+ "contacts than the whole day's cold-reachout allowance; split it into smaller batches.";
+
// EngineRegistry.require() answers 400 for a session with no engine; ENGINE_NOT_READY_409 covers only
// an engine that exists but is not ready. The body variant is for routes that also validate a DTO.
const BODY_OR_SESSION_400 = 'The body failed validation, or the session is not started (no engine is running for it).';
@@ -194,7 +200,7 @@ export class GroupController {
@ApiResponse({ status: 201, description: 'Group created', type: GroupSummaryDto })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 403, description: ENGINE_REFUSED_403 })
- @ApiResponse({ status: 400, description: PARTICIPANT_ID_400 })
+ @ApiResponse({ status: 400, description: PACED_PARTICIPANT_400 })
@ApiResponse({
status: 503,
description:
@@ -225,7 +231,7 @@ export class GroupController {
@ApiResponse({ status: 503, description: PARTICIPANTS_503 })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 403, description: ENGINE_REFUSED_403 })
- @ApiResponse({ status: 400, description: PARTICIPANT_ID_400 })
+ @ApiResponse({ status: 400, description: PACED_PARTICIPANT_400 })
@HttpCode(HttpStatus.OK)
@ApiResponse({ status: 404, description: GROUP_NOT_FOUND_404 })
async addParticipants(