Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(openapi): declare the statuses and codes the routes already answer
Yudhi Armyndharis58b4bb94a6d6
diff --git a/openapi.json b/openapi.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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,