Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(storage): scope the S3 503 to a bucket not reachable since boot

Yudhi Armyndharisbcec914f117f
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 72ecc6289..4f266f8a8 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -5370,7 +5370,7 @@ Aggregate infrastructure status (database, Redis, queue, storage, engine).
The `queue.webhooks` counters are live BullMQ job counts (`pending` = waiting + active + delayed; plus `completed`/`failed`), degrading to zeros when the queue is disabled or Redis is unreachable. `redis.connected` is a live probe.
-`builtIn` (on `database`/`redis`/`storage`) reports whether OpenWA's own bundled container is actually running _and_ backing this service, detected live from the labelled container; when Docker is unreachable it falls back to the saved `*_BUILTIN` intent from `data/.env.generated`. In S3 mode `storage` additionally carries `bucket` (when one is configured) and `s3Available` (a throttled re-probe); in local mode neither key is present. `engine.webVersion`/`engine.webVersionSource` (`pinned` / `auto` / `native`) appear only on `whatsapp-web.js`; `webVersion` is `null` until the auto-resolve first succeeds.
+`builtIn` (on `database`/`redis`/`storage`) reports whether OpenWA's own bundled container is actually running _and_ backing this service, detected live from the labelled container; when Docker is unreachable it falls back to the saved `*_BUILTIN` intent from `data/.env.generated`. In S3 mode `storage` additionally carries `bucket` (when one is configured) and `s3Available` (re-probed, throttled, while false; once true it stays true until a restart, so a later outage does not clear it); in local mode neither key is present. `engine.webVersion`/`engine.webVersionSource` (`pinned` / `auto` / `native`) appear only on `whatsapp-web.js`; `webVersion` is `null` until the auto-resolve first succeeds.
**Errors:** `401` missing/invalid key · `403` key role < ADMIN
@@ -5824,7 +5824,7 @@ File count and total size in the active storage backend.
{ "storageType": "local", "count": 128, "sizeBytes": 5242880, "sizeMB": "5.00" }
```
-**Errors:** `401` · `403` · `500` · `503` `STORAGE_TYPE=s3` but the bucket is unreachable or its credentials are missing (this route, the export and the import refuse rather than report on the local fallback directory)
+**Errors:** `401` · `403` · `500` · `503` `STORAGE_TYPE=s3` but the bucket has not been reachable since boot, or its credentials are missing (this route, the export and the import refuse rather than report on the local fallback directory; an outage after the bucket was reachable answers `500`)
---
@@ -5842,7 +5842,7 @@ Export all storage files into a `tar.gz` under `data/exports` and return its **s
`download` is a server filesystem path — feed it back to `POST /api/infra/storage/import`. The archive is auto-deleted after `STORAGE_EXPORT_TTL_MS` (default 1h).
-**Errors:** `401` · `403` · `500` · `503` S3 configured but unavailable
+**Errors:** `401` · `403` · `500` · `503` S3 configured but not reachable since boot (a later outage answers `500`)
---
@@ -5870,7 +5870,7 @@ Import storage files from a `tar.gz` located inside the `data/` directory.
`failed` counts archive entries the store refused to write; a bad or traversing entry is skipped without failing the rest. `imported` is `false` when entries failed and none was written.
-**Errors:** `400` missing/out-of-`data/`/not-found path · `401` · `403` · `500` · `503` S3 configured but unavailable
+**Errors:** `400` missing/out-of-`data/`/not-found path · `401` · `403` · `500` · `503` S3 configured but not reachable since boot (a later outage answers `200` with `imported: false` and the entries in `failed`)
---
diff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.md
index 66c0fedc7..751813c7e 100644
--- a/docs/14-migration-guide.md
+++ b/docs/14-migration-guide.md
@@ -221,8 +221,11 @@ curl -X POST 'http://localhost:2785/api/infra/import-data' \
OpenWA v0.2+ supports migrating media files between storage backends:
On an S3/MinIO backend, confirm `GET /api/infra/status` reports `storage.s3Available: true` before the
-export (S3 to Local) and before the import (Local to S3). While the bucket is unusable these routes
-answer `503` instead of running against the local fallback directory.
+export (S3 to Local) and before the import (Local to S3). Until the bucket has been reachable once since
+boot, these routes answer `503` instead of running against the local fallback directory. `s3Available`
+does not go back to `false` until a restart, so it shows the bucket came up, not that it is still up: an
+outage after that makes the count and the export fail with `500`, and the import answer `imported: false`
+with the entries counted in `failed`.
```bash
# Step 1: Check current storage file count