Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(baileys): tell a WhatsApp rate limit apart from a timeout

Yudhi Armyndharis2fd5cbbdf7fa
diff --git a/src/common/errors/engine-throttled.error.ts b/src/common/errors/engine-throttled.error.ts
new file mode 100644
index 000000000..12be45211
--- /dev/null
+++ b/src/common/errors/engine-throttled.error.ts
@@ -0,0 +1,9 @@
+import { EngineTransportError } from './engine-transport.error';
+
+/**
+ * An {@link EngineTransportError} (HTTP 503) for a request WhatsApp throttled (its code 429) rather than
+ * left unanswered. A throttled request was turned away before it ran, so nothing was applied and nobody
+ * was contacted, while a plain EngineTransportError leaves the outcome unknown. Callers that charge a
+ * budget up front can tell the two apart and give a throttled request's reservation back.
+ */
+export class EngineThrottledError extends EngineTransportError {}
diff --git a/src/engine/adapters/baileys-groups.ts b/src/engine/adapters/baileys-groups.ts
index 370e5218a..829293642 100644
--- a/src/engine/adapters/baileys-groups.ts
+++ b/src/engine/adapters/baileys-groups.ts
@@ -14,6 +14,7 @@ import { GroupNotFoundError } from '../../common/errors/group-not-found.error';
import { resolveMediaBuffer } from './baileys-messaging';
import { EngineRefusedError } from '../../common/errors/engine-refused.error';
import { EngineTransportError } from '../../common/errors/engine-transport.error';
+import { EngineThrottledError } from '../../common/errors/engine-throttled.error';
import { InvalidInviteCodeError } from '../../common/errors/invalid-invite-code.error';
import { type createLogger } from '../../common/services/logger.service';
import { BAILEYS_QUERY_BUDGET_MS, withQueryDeadline } from './baileys-query-deadline';
@@ -74,7 +75,8 @@ export function refusedStatusCode(error: unknown): number | undefined {
* connection as a permissions problem.
*
* WA codes 408 and 429 (timed out, rate limited) become EngineTransportError (503) instead: a
- * throttled caller has not been refused, and a retry may succeed.
+ * throttled caller has not been refused, and a retry may succeed. A 429 is the EngineThrottledError
+ * subclass, since a throttled request was not applied and a paced write can give its budget back.
*
* `notFound`, when given, takes WA code 404 (item-not-found) instead: a caller whose request names a
* single resource maps it to that resource's not-found error rather than a permissions refusal.
@@ -92,8 +94,11 @@ export async function mapServerRefusal<T>(
if (code === 404 && notFound) {
throw notFound();
}
- if (code === 408 || code === 429) {
- throw new EngineTransportError(`${operation} was rate-limited or timed out by WhatsApp (code ${code})`);
+ if (code === 429) {
+ throw new EngineThrottledError(`${operation} was rate-limited by WhatsApp (code ${code})`);
+ }
+ if (code === 408) {
+ throw new EngineTransportError(`${operation} was timed out by WhatsApp (code ${code})`);
}
if (code !== undefined && code >= 400 && code < 500) {
throw new EngineRefusedError(
diff --git a/src/engine/adapters/baileys-refused-status.spec.ts b/src/engine/adapters/baileys-refused-status.spec.ts
index 932c65bcd..f41716a39 100644
--- a/src/engine/adapters/baileys-refused-status.spec.ts
+++ b/src/engine/adapters/baileys-refused-status.spec.ts
@@ -3,6 +3,7 @@ import { refusedStatusCode, mapServerRefusal } from './baileys-groups';
import { wmexRefusalCode } from './baileys-channels';
import { EngineRefusedError } from '../../common/errors/engine-refused.error';
import { EngineTransportError } from '../../common/errors/engine-transport.error';
+import { EngineThrottledError } from '../../common/errors/engine-throttled.error';
/**
* `refusedStatusCode` decides whether a Baileys failure was a SERVER refusal (map to 403/404) or a
@@ -85,4 +86,11 @@ describe('mapServerRefusal', () => {
).rejects.toBeInstanceOf(EngineTransportError);
}
});
+
+ it('marks only a rate limit as throttled, so a pre-charged budget can be given back', async () => {
+ const reject = (code: number) => () => Promise.reject(new Boom('refused', { data: code }));
+ await expect(mapServerRefusal('Creating the group', reject(429))).rejects.toBeInstanceOf(EngineThrottledError);
+ // A server timeout leaves the outcome unknown: it stays a plain transport error.
+ await expect(mapServerRefusal('Creating the group', reject(408))).rejects.not.toBeInstanceOf(EngineThrottledError);
+ });
});