Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(openapi): declare the statuses and codes the routes already answer

Yudhi Armyndharis58b4bb94a6d6
diff --git a/openapi.json b/openapi.json
index 2de05a1bd..0ae455cd4 100644
--- a/openapi.json
+++ b/openapi.json
@@ -4483,6 +4483,16 @@
}
}
},
+ "404": {
+ "description": "No such message: the id is outside the engine's lookup window (roughly the last hundred messages of the chat, or absent from the Baileys store) or the message was revoked.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"409": {
"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly.",
"content": {
@@ -4735,6 +4745,16 @@
}
}
},
+ "404": {
+ "description": "No such message: the id is outside the engine's lookup window (roughly the last hundred messages of the chat, or absent from the Baileys store) or the message was revoked.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"409": {
"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly.",
"content": {
@@ -4875,6 +4895,16 @@
}
}
},
+ "404": {
+ "description": "No such message: the id is outside the engine's lookup window (roughly the last hundred messages of the chat, or absent from the Baileys store) or the message was revoked.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"409": {
"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly.",
"content": {
@@ -5016,6 +5046,16 @@
}
}
},
+ "404": {
+ "description": "No such message: the id is outside the engine's lookup window (roughly the last hundred messages of the chat, or absent from the Baileys store) or the message was revoked.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"409": {
"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly.",
"content": {
@@ -5157,6 +5197,16 @@
}
}
},
+ "404": {
+ "description": "No such message: the id is outside the engine's lookup window (roughly the last hundred messages of the chat, or absent from the Baileys store) or the message was revoked.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"409": {
"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly.",
"content": {
@@ -5299,6 +5349,16 @@
}
}
},
+ "404": {
+ "description": "No such message: the id is outside the engine's lookup window (roughly the last hundred messages of the chat, or absent from the Baileys store) or the message was revoked.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"409": {
"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly.",
"content": {
@@ -5430,6 +5490,16 @@
}
}
},
+ "404": {
+ "description": "No such message: the id is outside the engine's lookup window (roughly the last hundred messages of the chat, or absent from the Baileys store) or the message was revoked.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"409": {
"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly.",
"content": {
@@ -5560,6 +5630,16 @@
}
}
},
+ "404": {
+ "description": "No such message: the id is outside the engine's lookup window (roughly the last hundred messages of the chat, or absent from the Baileys store) or the message was revoked.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"409": {
"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly.",
"content": {
@@ -5704,6 +5784,16 @@
}
}
},
+ "404": {
+ "description": "No such message: the id is outside the engine's lookup window (roughly the last hundred messages of the chat, or absent from the Baileys store) or the message was revoked.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"409": {
"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly.",
"content": {
@@ -8114,6 +8204,9 @@
}
}
}
+ },
+ "503": {
+ "description": "Shutdown teardown has begun: every route except /api/health and /api/health/* answers 503 then. Probe /api/health/live for a check that survives teardown."
}
},
"summary": "Health check endpoint",
@@ -17900,7 +17993,7 @@
},
"info": {
"title": "OpenWA API",
- "description": "Open Source WhatsApp API Gateway - Free, Self-Hosted HTTP API\n\n**Gateway-wide responses.** Three statuses are returned by middleware before routing, so any operation can emit them:\n\n- `415 Unsupported Media Type` — the request body carries a `Content-Encoding` other than `identity`. The aggregate in-flight body cap counts wire bytes, so a compressed body would be admitted on its compressed size and then inflated past the memory it is meant to bound. Send the body uncompressed.\n- `413 Payload Too Large`: the declared `Content-Length` is more than the gateway could hold in flight for this caller even when idle. The body is not read; retrying it unchanged cannot succeed.\n- `503 Service Unavailable` with `Retry-After` — the gateway already has too much request body data in flight. The body is not read; retry after the given delay.\n\nEvery operation that takes an API key can also answer `429 Too Many Requests` (the per-IP rate-limit windows; with send pacing on, a send can also be refused with `code: SEND_PACING_LIMITED` and `retryAfterSeconds`) and `500 Internal Server Error` (an unexpected failure, or `code: ENGINE_PAGE_ERROR` when WhatsApp Web threw inside the page during a whatsapp-web.js send or status post). Error bodies follow the `ErrorResponse` schema.",
+ "description": "Open Source WhatsApp API Gateway - Free, Self-Hosted HTTP API\n\n**Gateway-wide responses.** Three statuses are returned by middleware before routing, so any operation can emit them:\n\n- `415 Unsupported Media Type` — the request body carries a `Content-Encoding` other than `identity`. The aggregate in-flight body cap counts wire bytes, so a compressed body would be admitted on its compressed size and then inflated past the memory it is meant to bound. Send the body uncompressed.\n- `413 Payload Too Large`: the declared `Content-Length` is more than the gateway could hold in flight for this caller even when idle. The body is not read; retrying it unchanged cannot succeed.\n- `503 Service Unavailable` with `Retry-After` — the gateway already has too much request body data in flight (the body is not read; retry after the given delay), or, without `Retry-After`, shutdown teardown has begun: every route except `/api/health` and `/api/health/*` then answers it with `Connection: close`.\n\nEvery operation that takes an API key can also answer `429 Too Many Requests` (the per-IP rate-limit windows; with send pacing on, a send can also be refused with `code: SEND_PACING_LIMITED` and `retryAfterSeconds`) and `500 Internal Server Error` (an unexpected failure, or `code: ENGINE_PAGE_ERROR` when WhatsApp Web threw inside the page during a whatsapp-web.js send or status post). Error bodies follow the `ErrorResponse` schema.",
"version": "0.24.0",
"contact": {
"name": "OpenWA",
@@ -22899,7 +22992,7 @@
]
},
"warnings": {
- "description": "Why the restore was rolled back (per-row failures, a failed session ownership restore, chat-state re-key or restored-row cleanup, or a backup with no rows). Non-empty only when `imported` is false; non-fatal messages are in `notices`.",
+ "description": "Why the restore was rolled back (per-row failures, a failed session ownership restore, chat-state re-key or restored-row cleanup, a failed trim of the send idempotency claims, or a backup with no rows). Non-empty only when `imported` is false; non-fatal messages are in `notices`.",
"example": [],
"type": "array",
"items": {
@@ -25561,12 +25654,19 @@
},
"code": {
"type": "string",
- "description": "A stable machine-readable reason, on some errors only: SESSION_NAME_TEARDOWN_PENDING (409), SESSION_STOP_INCOMPLETE, SESSION_LOGOUT_INCOMPLETE and SESSION_FORCE_KILL_INCOMPLETE (502), SEND_PACING_LIMITED (429), ENGINE_PAGE_ERROR (500, whatsapp-web.js: WhatsApp Web threw inside the page during a send or status post), IMPORT_ALREADY_RUNNING, EXPORT_IN_PROGRESS, IMPORT_WOULD_ORPHAN_ENGINES and IMPORT_NESTED_TRANSACTION (409)."
+ "description": "A stable machine-readable reason, on some errors only: SESSION_NAME_TEARDOWN_PENDING (409), SESSION_STOP_INCOMPLETE, SESSION_LOGOUT_INCOMPLETE and SESSION_FORCE_KILL_INCOMPLETE (502), SEND_PACING_LIMITED (429), ENGINE_PAGE_ERROR (500, whatsapp-web.js: WhatsApp Web threw inside the page during a send or status post), IMPORT_ALREADY_RUNNING, EXPORT_IN_PROGRESS, IMPORT_WOULD_ORPHAN_ENGINES and IMPORT_NESTED_TRANSACTION (409), IDEMPOTENCY_KEY_INVALID (400), IDEMPOTENCY_KEY_REUSED (422), IDEMPOTENCY_KEY_IN_PROGRESS and IDEMPOTENCY_OUTCOME_UNKNOWN (409), POLL_OPTION_NOT_FOUND (400, whatsapp-web.js vote-poll)."
},
"retryAfterSeconds": {
"type": "integer",
"description": "With SEND_PACING_LIMITED: seconds until the session accepts sends again."
},
+ "validOptions": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "With POLL_OPTION_NOT_FOUND: the option texts the poll offers."
+ },
"pageError": {
"type": "object",
"required": [
diff --git a/src/config/swagger.config.ts b/src/config/swagger.config.ts
index dcf810b75..7c433ab90 100644
--- a/src/config/swagger.config.ts
+++ b/src/config/swagger.config.ts
@@ -124,12 +124,20 @@ const ERROR_RESPONSE: SchemaObject = {
'SESSION_STOP_INCOMPLETE, SESSION_LOGOUT_INCOMPLETE and SESSION_FORCE_KILL_INCOMPLETE (502), ' +
'SEND_PACING_LIMITED (429), ' +
'ENGINE_PAGE_ERROR (500, whatsapp-web.js: WhatsApp Web threw inside the page during a send or status post), ' +
- 'IMPORT_ALREADY_RUNNING, EXPORT_IN_PROGRESS, IMPORT_WOULD_ORPHAN_ENGINES and IMPORT_NESTED_TRANSACTION (409).',
+ 'IMPORT_ALREADY_RUNNING, EXPORT_IN_PROGRESS, IMPORT_WOULD_ORPHAN_ENGINES and IMPORT_NESTED_TRANSACTION (409), ' +
+ 'IDEMPOTENCY_KEY_INVALID (400), IDEMPOTENCY_KEY_REUSED (422), ' +
+ 'IDEMPOTENCY_KEY_IN_PROGRESS and IDEMPOTENCY_OUTCOME_UNKNOWN (409), ' +
+ 'POLL_OPTION_NOT_FOUND (400, whatsapp-web.js vote-poll).',
},
retryAfterSeconds: {
type: 'integer',
description: 'With SEND_PACING_LIMITED: seconds until the session accepts sends again.',
},
+ validOptions: {
+ type: 'array',
+ items: { type: 'string' },
+ description: 'With POLL_OPTION_NOT_FOUND: the option texts the poll offers.',
+ },
pageError: {
type: 'object',
required: ['name', 'message'],
@@ -212,7 +220,9 @@ export function createSwaggerConfig(): Omit<OpenAPIObject, 'paths'> {
'hold in flight for this caller even when idle. The body is not read; retrying it unchanged ' +
'cannot succeed.\n' +
'- `503 Service Unavailable` with `Retry-After` — the gateway already has too much ' +
- 'request body data in flight. The body is not read; retry after the given delay.\n\n' +
+ 'request body data in flight (the body is not read; retry after the given delay), or, without ' +
+ '`Retry-After`, shutdown teardown has begun: every route except `/api/health` and ' +
+ '`/api/health/*` then answers it with `Connection: close`.\n\n' +
'Every operation that takes an API key can also answer `429 Too Many Requests` (the per-IP ' +
'rate-limit windows; with send pacing on, a send can also be refused with `code: ' +
'SEND_PACING_LIMITED` and `retryAfterSeconds`) and `500 Internal Server Error` (an ' +
diff --git a/src/modules/infra/dto/infra-response.dto.ts b/src/modules/infra/dto/infra-response.dto.ts
index 275c12ebe..821829460 100644
--- a/src/modules/infra/dto/infra-response.dto.ts
+++ b/src/modules/infra/dto/infra-response.dto.ts
@@ -505,7 +505,8 @@ export class InfraImportDataResponseDto {
type: [String],
description:
'Why the restore was rolled back (per-row failures, a failed session ownership restore, chat-state re-key ' +
- 'or restored-row cleanup, or a backup with no rows). Non-empty only when `imported` is false; non-fatal ' +
+ 'or restored-row cleanup, a failed trim of the send idempotency claims, or a backup with no rows). Non-empty ' +
+ 'only when `imported` is false; non-fatal ' +
'messages are in `notices`.',
example: [],
})
diff --git a/src/modules/infra/infra-status.controller.ts b/src/modules/infra/infra-status.controller.ts
index 06c923fcf..022286592 100644
--- a/src/modules/infra/infra-status.controller.ts
+++ b/src/modules/infra/infra-status.controller.ts
@@ -293,6 +293,12 @@ export class InfraStatusController {
description: 'Process is up. This route does not probe dependencies — read /infra/status for those.',
type: InfraHealthResponseDto,
})
+ @ApiResponse({
+ status: 503,
+ description:
+ 'Shutdown teardown has begun: every route except /api/health and /api/health/* answers 503 then. ' +
+ 'Probe /api/health/live for a check that survives teardown.',
+ })
healthCheck(): { status: string; timestamp: string } {
return {
status: 'ok',
diff --git a/src/modules/message/message.controller.ts b/src/modules/message/message.controller.ts
index 955a11d61..b14b19a7f 100644
--- a/src/modules/message/message.controller.ts
+++ b/src/modules/message/message.controller.ts
@@ -216,6 +216,7 @@ export class MessageController {
description: 'Session not active or invalid request',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
+ @ApiResponse({ status: 404, description: MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 501, description: `${CUSTOM_LINK_PREVIEW_501} ${QUOTED_SEND_501}` })
@ApiResponse({ status: 503, description: RECIPIENT_LOOKUP_503 })
async sendText(@Param('sessionId') sessionId: string, @Body() dto: SendTextMessageDto): Promise<MessageResponseDto> {
@@ -266,6 +267,7 @@ export class MessageController {
description: 'Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
+ @ApiResponse({ status: 404, description: MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 501, description: `${CHANNEL_MEDIA_501} ${QUOTED_SEND_501}` })
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
@ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${RECIPIENT_LOOKUP_503}` })
@@ -293,6 +295,7 @@ export class MessageController {
description: 'Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
+ @ApiResponse({ status: 404, description: MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 501, description: `${CHANNEL_MEDIA_501} ${QUOTED_SEND_501}` })
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
@ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${RECIPIENT_LOOKUP_503}` })
@@ -320,6 +323,7 @@ export class MessageController {
description: 'Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
+ @ApiResponse({ status: 404, description: MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 501, description: `${CHANNEL_MEDIA_501} ${QUOTED_SEND_501}` })
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
@ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${RECIPIENT_LOOKUP_503}` })
@@ -347,6 +351,7 @@ export class MessageController {
description: 'Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
+ @ApiResponse({ status: 404, description: MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 501, description: `${CHANNEL_MEDIA_501} ${QUOTED_SEND_501}` })
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
@ApiResponse({ status: 503, description: `${MEDIA_URL_PROXY_503} ${RECIPIENT_LOOKUP_503}` })
@@ -372,6 +377,7 @@ export class MessageController {
type: MessageResponseDto,
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
+ @ApiResponse({ status: 404, description: MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 400, description: RECIPIENT_UNREACHABLE_400 })
@ApiResponse({ status: 501, description: wwebjsRefuses501(`a location to ${CHANNEL_OR_BROADCAST}`) })
@ApiResponse({ status: 503, description: RECIPIENT_LOOKUP_503 })
@@ -392,6 +398,7 @@ export class MessageController {
type: MessageResponseDto,
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
+ @ApiResponse({ status: 404, description: MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 400, description: RECIPIENT_UNREACHABLE_400 })
@ApiResponse({ status: 501, description: wwebjsRefuses501(`a contact card to ${CHANNEL_OR_BROADCAST}`) })
@ApiResponse({ status: 503, description: RECIPIENT_LOOKUP_503 })
@@ -412,6 +419,7 @@ export class MessageController {
type: MessageResponseDto,
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
+ @ApiResponse({ status: 404, description: MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 400, description: RECIPIENT_UNREACHABLE_400 })
@ApiResponse({
status: 501,
@@ -439,6 +447,7 @@ export class MessageController {
type: MessageResponseDto,
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
+ @ApiResponse({ status: 404, description: MESSAGE_NOT_FOUND_404 })
@ApiResponse({ status: 400, description: RECIPIENT_UNREACHABLE_400 })
@ApiResponse({
status: 501,