@friggframework/core 2.0.0--canary.654.6d3a665.0 → 2.0.0--canary.657.ebe5c60.0

package/CLAUDE.md

@@ -369,6 +369,48 @@ class MyIntegration extends IntegrationBase {
 - `ApiKeyRequester` - API key authentication
 - `BasicAuthRequester` - Basic authentication
 
+**Rate limits** (ADR-049): an API module declares `static rateLimit` on its
+`Requester` subclass. For a throttled response the Requester looks for a hint
+in this order:
+
+| Step | Source |
+|---|---|
+| 1 | `classify({ status, headers, body })` of the module. It recognises a limit that is not a plain 429 (a 403 limit code, a `policyName` in the body) and may name only a `reason` |
+| 2 | The header parsers in `parsers` order. Default: `retryAfter`, `resetHeaders`, `ietf` |
+| 3 | The static policy: `minRetryAfterMs`, or the `perMs` of the window named by the `reason` |
+| 4 | The fixed `backOff` ladder (1, 3, 10, 30, 60, 180 s) |
+
+- A 429 with no hint from steps 1 to 3 keeps today's ladder: the same calls,
+  the same delays, then a plain `FetchError`. Nothing budgets it.
+- With a hint, the wait is `max(hint, minRetryAfterMs, 1 s)` plus at most 10 %
+  jitter. The total sleep of one request is capped at `maxInProcessWaitMs`
+  (default 5 minutes) and at the time left in the invocation less one request
+  timeout (`remainingInvocationMs()`).
+- A wait that does not fit throws `RateLimitError` (`isRateLimited`, `retryAt`,
+  `waitMs`, `reason`, `policy`, `source`, `module`, `scopeKey`). The queue
+  worker does not halt it, whatever its status.
+- `Retry-After` is read on a 429 only. Another status counts only when
+  `classify` recognises it. A 5xx keeps the 5xx ladder.
+- `maxInProcessWaitMs: 0` turns off sleeping: every hinted wait throws.
+- A module that does not use the Requester (for example one on jsforce) calls
+  `classifyRateLimit(policy, { status, headers, body })` around its own client
+  and throws `RateLimitError` itself.
+
+```javascript
+class Api extends OAuth2Requester {
+    static rateLimit = {
+        scope: 'entity',
+        minRetryAfterMs: 1_000,
+        classify({ status, body }) {
+            if (status === 403 && body?.code === 'DAILY_LIMIT') {
+                return { reason: 'daily', waitMs: 60 * 60_000 };
+            }
+            return null;
+        },
+    };
+}
+```
+
 **Module Factory**:
 - `ModuleFactory` - Creates and configures API module instances
 - Handles credential injection
@@ -477,7 +519,8 @@ handlers (`{ req, res, next }`) and `this.on` events do not.
 `isLastAttempt` is `false` when either count is unknown: a local or non-SQS
 invocation, or a queue whose redrive policy the stack does not own
 (`ownership.queue: 'external'`). The value is information only: core still
-rethrows retryable errors and discards halt errors (4xx except 408/429).
+rethrows retryable errors and discards halt errors (4xx except 408, 429 and
+errors with `isRateLimited`).
 
 Use it to end a run or count lost work on the final try: when a retryable
 error (429, 5xx, network) is about to be rethrown and `isLastAttempt` is
@@ -500,6 +543,58 @@ The single source of the max receive count is
 devtools integration builder uses it for the queue's `RedrivePolicy` and sets
 it as `FRIGG_QUEUE_MAX_RECEIVE_COUNT` on the queue worker function.
 
+**Rate-limit deferral** (ADR-049): when a queue handler throws an error with
+`isRateLimited` and a `retryAt` (a `RateLimitError` from the Requester, or one a
+module throws), `Worker.run` does not give the message back to SQS for a 30
+minute redelivery that spends one of its three receives. It puts the message
+back so it runs at `retryAt`:
+
+| Wait | What the worker does | Record |
+|---|---|---|
+| Up to 900 s | Sends the same body again with `DelaySeconds`, then acknowledges the old message | handled |
+| Over 900 s, and `SCHEDULER_ROLE_ARN` is set | Creates a one-time EventBridge schedule at `retryAt` that sends the body to the queue, then acknowledges | handled |
+| Over 900 s, no scheduler | Extends the message's visibility timeout to `retryAt` (12 h at most). This uses one receive | reported failed |
+
+- The new message starts at receive count 1. A deferred body carries
+  `_frigg: { deferrals, firstDeferredAt }`; `_frigg` is reserved and the handler
+  never sees it.
+- Two caps bound it: `FRIGG_QUEUE_MAX_DEFERRALS` (default 10) and
+  `FRIGG_QUEUE_MAX_DEFERRED_MS` (default 24 h, from the first deferral to the
+  retry time). Past a cap, with no `retryAt`, with no event source ARN or on a
+  FIFO queue, the record fails like any retryable error and `delivery`
+  applies.
+- The mock scheduler is never used for a deferral: a schedule kept in memory
+  would be lost with the acknowledged message.
+- With a `processId` in the message, the worker writes
+  `Process.context.rateLimit = { status: 'WAITING' | 'EXHAUSTED', mechanism,
+  retryAt, reason, module, deferrals, updatedAt }`, and `null` after the message
+  ran. `EXHAUSTED` means a cap ended the deferrals, or a visibility change came
+  on the last delivery.
+- Delivery stays at least once. The new message is sent before the old one is
+  acknowledged, so a crash between the two can run the work twice.
+- Handlers check `delivery.isLastAttempt` first, then rethrow. The delay and
+  schedule tiers send a new message, so they never reach the last attempt. The
+  visibility tier and a cap use a receive: on the last one the worker writes an
+  ERROR (`frigg.worker.record_lost_rate_limited`), and the handler has this one
+  chance to end the run.
+
+```javascript
+async processBatch({ data, delivery }) {
+    try {
+        await this.syncPage(data);
+    } catch (error) {
+        if (delivery?.isLastAttempt) return this.failRun(data.processId, error);
+        throw error; // a RateLimitError too: core puts the message back at retryAt
+    }
+}
+```
+
+Records: `frigg.worker.record_deferred` (`mechanism` `delay` or `schedule`),
+`record_visibility_extended`, `record_deferral_capped`,
+`record_lost_rate_limited` and `rate_limit_state_failed`. A queue in a stack
+that does not own it (`ownership.queue: 'external'`) needs its own
+`sqs:ChangeMessageVisibility` and scheduler access.
+
 ### 8. Error Handling (`/errors`)
 
 **Purpose**: Standardized error types with proper HTTP semantics.
@@ -507,6 +602,7 @@ it as `FRIGG_QUEUE_MAX_RECEIVE_COUNT` on the queue worker function.
 **Error Types**:
 - `BaseError` - Base error class
 - `FetchError` - HTTP request failures
+- `RateLimitError` - A `FetchError` for a limit the provider or the module's policy says when to retry (`retryAt`)
 - `HaltError` - Stop processing without retry
 - `RequiredPropertyError` - Missing required parameters
 - `ParameterTypeError` - Invalid parameter type

package/core/CLAUDE.md

@@ -79,6 +79,25 @@ await worker.send({
 }, delaySeconds);
 ```
 
+**Rate-limit deferral** (ADR-049): `run()` handles an error with `isRateLimited`
+and a `retryAt` through `defer(record, body, error, delivery)`, which returns
+`{ outcome }`:
+- `acked`: the message was sent again with `DelaySeconds` (wait up to 900 s) or
+  scheduled with the one-time scheduler (longer wait). The record is handled.
+- `failed`: the visibility timeout was extended to `retryAt`, or a cap
+  (`FRIGG_QUEUE_MAX_DEFERRALS`, `FRIGG_QUEUE_MAX_DEFERRED_MS`) ended the
+  deferrals. The record is reported failed.
+- `skipped`: no `retryAt`, no `eventSourceARN`, a FIFO queue, or a failed send.
+  The record fails as any error does, and `record_failed` carries
+  `deferral: { skipped }`.
+
+Subclasses override two no-op hooks to keep run state: `recordRateLimitWait(body,
+error, state)` runs after the message was put back, and `clearRateLimitWait(body)`
+runs after a deferred or redelivered message succeeded. A failing hook logs
+`frigg.worker.rate_limit_state_failed` and never changes the outcome. The queue
+worker of an integration (`createQueueWorker`) writes `Process.context.rateLimit`
+in them. See `packages/core/CLAUDE.md` section 7.
+
 ### Delegate Pattern System (`Delegate.js:3-27`)
 
 **Purpose**: Observer/delegation pattern for decoupled component communication
@@ -130,7 +149,7 @@ class MyIntegration extends Delegate {
 ### Lambda Handler Lifecycle
 1. **Pre-Execution Setup**:
    ```javascript
-   runInvocationScope({ requestId, handlerName, method, route, invocation }, …); // Logger scope for the invocation
+   runInvocationScope({ requestId, handlerName, method, route, invocation }, …); // Logger scope + invocation deadline (remainingInvocationMs())
    log.info('Handler invoked', { eventName: 'frigg.handler.invoked' });
    await secretsToEnv();                     // Secrets Manager injection
    await parametersToEnv();                  // SSM Parameter Store fetch (only when SSM_PARAMETER_PREFIX + FRIGG_SSM_OFFLOADED_KEYS are set)
@@ -226,6 +245,8 @@ const handler = createHandler({
    - Logs error but returns success
    - Prevents infinite retries for known issues
    - Used for graceful degradation scenarios
+   - The queue worker sets it on a 4xx except 408, 429 and errors with
+     `isRateLimited` (a provider limit signalled with 403 clears with time)
 
 ### Logging Strategy
 ```javascript

package/core/Worker.js

@@ -1,14 +1,39 @@
-const { SQSClient, GetQueueUrlCommand, SendMessageCommand } = require('@aws-sdk/client-sqs');
+const { randomUUID } = require('node:crypto');
+const {
+    SQSClient,
+    GetQueueUrlCommand,
+    SendMessageCommand,
+    ChangeMessageVisibilityCommand,
+} = require('@aws-sdk/client-sqs');
 const _ = require('lodash');
 const { RequiredPropertyError } = require('../errors');
 const { get } = require('../assertions');
 const { readQueueDelivery } = require('../queues/queue-delivery');
+const { awsConfigOptions } = require('../queues/queuer-util');
+const {
+    MAX_DELAY_SECONDS,
+    MAX_VISIBILITY_TIMEOUT_SECONDS,
+    isDeferralCapped,
+    nextDeferral,
+    readDeferral,
+    readDeferralLimits,
+    withDeferral,
+} = require('../queues/queue-deferral');
 const { runMessageScope } = require('./invocation-scope');
-const { getLogger } = require('../logs');
+const { getLogger, serializeError } = require('../logs');
 
-const sqs = new SQSClient({ region: process.env.AWS_REGION });
+const sqs = new SQSClient({
+    region: process.env.AWS_REGION,
+    ...awsConfigOptions(),
+});
 const log = getLogger('frigg.worker');
 
+const validDate = (value) =>
+    value instanceof Date && !Number.isNaN(value.getTime()) ? value : null;
+const queueNameOf = (arn) =>
+    typeof arn === 'string' && arn ? arn.split(':').pop() : undefined;
+const causeOf = (error) => serializeError(error).message;
+
 class Worker {
     async getQueueURL(params) {
         // Passing params in because there will be multiple QueueNames
@@ -33,12 +58,31 @@ class Worker {
                 // messageId, receiveCount and the event come from the scope.
                 log.debug('Record started', { eventName: 'frigg.worker.record_started' });
 
+                const delivery = readQueueDelivery(record);
+                let runParams;
                 try {
-                    const runParams = JSON.parse(record.body);
+                    runParams = JSON.parse(record.body);
                     this._validateParams(runParams);
-                    await this._run(runParams, context, readQueueDelivery(record));
+                    await this._run(runParams, context, delivery);
+                    await this._clearDeferredState(runParams, delivery);
                     log.debug('Record succeeded', { eventName: 'frigg.worker.record_succeeded' });
                 } catch (error) {
+                    let deferral;
+                    if (error.isRateLimited && runParams) {
+                        deferral = await this.defer(
+                            record,
+                            runParams,
+                            error,
+                            delivery
+                        );
+                        if (deferral.outcome === 'acked') return;
+                        if (deferral.outcome === 'failed') {
+                            batchItemFailures.push({
+                                itemIdentifier: record.messageId,
+                            });
+                            return;
+                        }
+                    }
                     if (error.isHaltError) {
                         // HaltError means "discard this message, don't retry".
                         // Treat as success so SQS deletes it from the queue.
@@ -55,6 +99,14 @@ class Worker {
                     log.warn('Record failed, returned for retry', {
                         eventName: 'frigg.worker.record_failed',
                         error,
+                        ...(deferral && {
+                            deferral: {
+                                skipped: deferral.skipped,
+                                ...(deferral.cause && {
+                                    cause: causeOf(deferral.cause),
+                                }),
+                            },
+                        }),
                     });
                     batchItemFailures.push({ itemIdentifier: record.messageId });
                 }
@@ -75,6 +127,240 @@ class Worker {
         // parameters
     }
 
+    /**
+     * Puts a rate-limited message back so it runs at `error.retryAt`, without
+     * spending a receive. The message is sent again with a delay of up to 900 s,
+     * or scheduled with the one-time scheduler, or has its visibility timeout
+     * extended. The new message goes out before the old one is acknowledged, so
+     * delivery stays at least once.
+     *
+     * @returns {Promise<{outcome: 'acked'|'failed'|'skipped', skipped?: string, cause?: Error}>}
+     *   `acked`: the message is handled. `failed`: report the record failed and
+     *   let SQS redeliver it. `skipped`: nothing was done; fail the record as
+     *   any other error.
+     */
+    async defer(record, body, error, delivery) {
+        const retryAt = validDate(error.retryAt);
+        if (!retryAt) return { outcome: 'skipped', skipped: 'no_retry_at' };
+        const queueName = queueNameOf(record.eventSourceARN);
+        if (!queueName || queueName.endsWith('.fifo')) {
+            return { outcome: 'skipped', skipped: 'no_event_source' };
+        }
+
+        const now = Date.now();
+        const waitMs = Math.max(0, retryAt.getTime() - now);
+        const deferral = nextDeferral(body, now);
+        const details = {
+            waitMs,
+            retryAt: retryAt.toISOString(),
+            deferrals: deferral.deferrals,
+            firstDeferredAt: deferral.firstDeferredAt,
+            reason: error.reason,
+            module: error.module,
+            statusCode: error.statusCode,
+        };
+        const state = (status, mechanism) => ({
+            status,
+            mechanism,
+            deferrals: deferral.deferrals,
+            retryAt,
+        });
+
+        const limits = readDeferralLimits();
+        if (isDeferralCapped({ ...deferral, retryAt }, limits)) {
+            log.warn('Rate-limit deferral capped', {
+                eventName: 'frigg.worker.record_deferral_capped',
+                ...details,
+                maxDeferrals: limits.maxDeferrals,
+                maxDeferredMs: limits.maxDeferredMs,
+                deferredMs:
+                    retryAt.getTime() - Date.parse(deferral.firstDeferredAt),
+                error,
+            });
+            await this._recordWait(body, error, state('EXHAUSTED', 'none'));
+            this._logIfLost(delivery, error, details);
+            return { outcome: 'failed' };
+        }
+
+        const next = withDeferral(body, deferral);
+
+        if (waitMs <= MAX_DELAY_SECONDS * 1000) {
+            const delaySeconds = Math.ceil(waitMs / 1000);
+            try {
+                const queueUrl = await this._queueUrl(queueName);
+                await this.send({ ...next, QueueUrl: queueUrl }, delaySeconds);
+            } catch (cause) {
+                return { outcome: 'skipped', skipped: 'send_failed', cause };
+            }
+            await this._recordWait(body, error, state('WAITING', 'delay'));
+            log.warn('Record deferred', {
+                eventName: 'frigg.worker.record_deferred',
+                mechanism: 'delay',
+                delaySeconds,
+                ...details,
+                error,
+            });
+            return { outcome: 'acked' };
+        }
+
+        let scheduleError;
+        const scheduler = this.getSchedulerService();
+        if (scheduler) {
+            const scheduleName = `frigg-defer-${
+                record.messageId || randomUUID()
+            }`;
+            try {
+                await scheduler.scheduleOneTime({
+                    scheduleName,
+                    scheduleAt: retryAt,
+                    queueResourceId: record.eventSourceARN,
+                    payload: next,
+                });
+            } catch (cause) {
+                if (cause?.name !== 'ConflictException') scheduleError = cause;
+            }
+            if (!scheduleError) {
+                await this._recordWait(
+                    body,
+                    error,
+                    state('WAITING', 'schedule')
+                );
+                log.warn('Record deferred', {
+                    eventName: 'frigg.worker.record_deferred',
+                    mechanism: 'schedule',
+                    scheduleName,
+                    ...details,
+                    error,
+                });
+                return { outcome: 'acked' };
+            }
+        }
+
+        const visibilityTimeout = Math.min(
+            Math.ceil(waitMs / 1000),
+            MAX_VISIBILITY_TIMEOUT_SECONDS
+        );
+        try {
+            const queueUrl = await this._queueUrl(queueName);
+            await sqs.send(
+                new ChangeMessageVisibilityCommand({
+                    QueueUrl: queueUrl,
+                    ReceiptHandle: record.receiptHandle,
+                    VisibilityTimeout: visibilityTimeout,
+                })
+            );
+        } catch (cause) {
+            return { outcome: 'skipped', skipped: 'visibility_failed', cause };
+        }
+        await this._recordWait(
+            body,
+            error,
+            state(
+                delivery.isLastAttempt ? 'EXHAUSTED' : 'WAITING',
+                'visibility'
+            )
+        );
+        log.warn('Record visibility extended', {
+            eventName: 'frigg.worker.record_visibility_extended',
+            mechanism: 'visibility',
+            visibilityTimeout,
+            ...details,
+            ...(scheduleError && { scheduleError: causeOf(scheduleError) }),
+            error,
+        });
+        this._logIfLost(delivery, error, details);
+        return { outcome: 'failed' };
+    }
+
+    /**
+     * The one-time scheduler, or null when the stack has none. The mock
+     * scheduler is never used: a schedule kept in memory would be lost with
+     * the message.
+     */
+    getSchedulerService() {
+        if (this._schedulerService !== undefined) return this._schedulerService;
+        this._schedulerService = null;
+        if (
+            process.env.SCHEDULER_ROLE_ARN &&
+            process.env.SCHEDULER_PROVIDER !== 'mock'
+        ) {
+            const {
+                createSchedulerService,
+                SCHEDULER_PROVIDERS,
+            } = require('../infrastructure/scheduler/scheduler-service-factory');
+            this._schedulerService = createSchedulerService({
+                provider: SCHEDULER_PROVIDERS.EVENTBRIDGE,
+            });
+        }
+        return this._schedulerService;
+    }
+
+    /**
+     * Hook: the message was put back for a rate limit. Runs after it was sent.
+     * @param {Object} body The parsed message body.
+     * @param {Error} error The RateLimitError.
+     * @param {{status: 'WAITING'|'EXHAUSTED', mechanism: string, deferrals: number, retryAt: Date}} state
+     */
+    async recordRateLimitWait() {}
+
+    /**
+     * Hook: a message that was put back for a rate limit ran without error.
+     * @param {Object} body The parsed message body.
+     */
+    async clearRateLimitWait() {}
+
+    _queueUrl(queueName) {
+        this._queueUrls ??= new Map();
+        if (!this._queueUrls.has(queueName)) {
+            const lookup = this.getQueueURL({ QueueName: queueName }).catch(
+                (error) => {
+                    this._queueUrls.delete(queueName);
+                    throw error;
+                }
+            );
+            this._queueUrls.set(queueName, lookup);
+        }
+        return this._queueUrls.get(queueName);
+    }
+
+    async _recordWait(body, error, state) {
+        await this._runStateHook('record', () =>
+            this.recordRateLimitWait(body, error, state)
+        );
+    }
+
+    async _clearDeferredState(body, delivery) {
+        if (readDeferral(body).deferrals === 0 && !(delivery.receiveCount > 1))
+            return;
+        await this._runStateHook('clear', () => this.clearRateLimitWait(body));
+    }
+
+    async _runStateHook(operation, hook) {
+        try {
+            await hook();
+        } catch (error) {
+            log.warn('Rate-limit run state not written', {
+                eventName: 'frigg.worker.rate_limit_state_failed',
+                operation,
+                error,
+            });
+        }
+    }
+
+    _logIfLost(delivery, error, details) {
+        if (!delivery.isLastAttempt) return;
+        log.error(
+            'Rate-limited record lost: the message goes to the dead-letter queue next',
+            {
+                eventName: 'frigg.worker.record_lost_rate_limited',
+                retryAt: details.retryAt,
+                reason: error.reason,
+                module: error.module,
+                error,
+            }
+        );
+    }
+
     // returns the message id
     async send(params, delay = 0) {
         this._validateParams(params);

package/core/index.js

@@ -3,6 +3,10 @@ const { Worker } = require('./Worker');
 const { loadInstalledModules } = require('./load-installed-modules');
 const { createHandler } = require('./create-handler');
 const { runInvocationScope } = require('./invocation-scope');
+const {
+    runWithInvocationDeadline,
+    remainingInvocationMs,
+} = require('./invocation-deadline');
 
 module.exports = {
     Delegate,
@@ -10,4 +14,6 @@ module.exports = {
     loadInstalledModules,
     createHandler,
     runInvocationScope,
+    runWithInvocationDeadline,
+    remainingInvocationMs,
 };

package/core/invocation-deadline.js

@@ -0,0 +1,56 @@
+const { AsyncLocalStorage } = require('node:async_hooks');
+
+const STORE_KEY = Symbol.for('@friggframework/core.invocation-deadline');
+
+function storage() {
+    if (!globalThis[STORE_KEY]) {
+        globalThis[STORE_KEY] = new AsyncLocalStorage();
+    }
+    return globalThis[STORE_KEY];
+}
+
+/**
+ * Runs fn with the time the invocation ends, as epoch milliseconds. A nested
+ * scope can shorten the deadline and never extend it. A deadline that is not
+ * a finite number runs fn with no limit.
+ */
+function runWithInvocationDeadline(deadlineAt, fn) {
+    if (typeof deadlineAt !== 'number' || !Number.isFinite(deadlineAt)) {
+        return fn();
+    }
+    const outer = storage().getStore();
+    const effective = outer
+        ? Math.min(outer.deadlineAt, deadlineAt)
+        : deadlineAt;
+    return storage().run(Object.freeze({ deadlineAt: effective }), fn);
+}
+
+/**
+ * The end of a Lambda invocation, from its context. Undefined when the
+ * context cannot tell.
+ */
+function deadlineFromContext(context) {
+    try {
+        const remaining = context?.getRemainingTimeInMillis?.();
+        return typeof remaining === 'number' && Number.isFinite(remaining)
+            ? Date.now() + remaining
+            : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * Milliseconds left in the invocation. Infinity outside a deadline scope
+ * (tests, `frigg start`, scripts).
+ */
+function remainingInvocationMs(now = Date.now()) {
+    const store = storage().getStore();
+    return store ? Math.max(0, store.deadlineAt - now) : Infinity;
+}
+
+module.exports = {
+    deadlineFromContext,
+    remainingInvocationMs,
+    runWithInvocationDeadline,
+};

package/core/invocation-scope.js

@@ -1,6 +1,10 @@
 const { runInContext, LOGGER_SCOPE_KEY } = require('../logs/context');
 const { summarizeMessageBody } = require('../logs/summarize-event');
 const { flushSinks, hasFlushableSinks } = require('../logs/logger-runtime');
+const {
+    deadlineFromContext,
+    runWithInvocationDeadline,
+} = require('./invocation-deadline');
 
 // Bounds the tail latency telemetry adds to every warm invocation. Kept low so
 // an unreachable OTLP endpoint (e.g. a VPC Lambda with no NAT/egress) costs at
@@ -168,21 +172,26 @@ async function runInvocationScope(fields, fn, opts = {}) {
         flushTimeoutMs = DEFAULT_FLUSH_TIMEOUT_MS,
         context,
     } = opts;
-    return runInContext({ [LOGGER_SCOPE_KEY]: { ...(fields || {}) } }, async () => {
-        try {
-            return await fn();
-        } finally {
-            // Every step is guarded, so a flush never changes the result.
-            await flushInvocation({
-                telemetry,
-                usageRollup,
-                eventSummary,
-                shouldUseDatabase,
-                flushTimeoutMs,
-                context,
-            });
-        }
-    });
+    return runWithInvocationDeadline(deadlineFromContext(context), () =>
+        runInContext(
+            { [LOGGER_SCOPE_KEY]: { ...(fields || {}) } },
+            async () => {
+                try {
+                    return await fn();
+                } finally {
+                    // Every step is guarded, so a flush never changes the result.
+                    await flushInvocation({
+                        telemetry,
+                        usageRollup,
+                        eventSummary,
+                        shouldUseDatabase,
+                        flushTimeoutMs,
+                        context,
+                    });
+                }
+            }
+        )
+    );
 }
 
 function toCount(value) {

package/errors/fetch-error.js

@@ -55,12 +55,18 @@ class FetchError extends BaseError {
 
     static async create(options = {}) {
         const { response } = options;
-        let responseBody =
-            response && !response.bodyUsed && typeof response.text === 'function'
-                ? await response.text()
-                : null;
-        if (!responseBody) responseBody = options.responseBody ?? options.body;
-        return new FetchError({ ...options, responseBody });
+        const provided = options.responseBody ?? options.body;
+        let responseBody = provided;
+        if (
+            !responseBody &&
+            response &&
+            !response.bodyUsed &&
+            typeof response.text === 'function'
+        ) {
+            responseBody = (await response.text()) || provided;
+        }
+        const ErrorClass = typeof this === 'function' ? this : FetchError;
+        return new ErrorClass({ ...options, responseBody });
     }
 }
 

package/errors/index.js

@@ -1,6 +1,7 @@
 const { BaseError } = require('./base-error');
 const { FetchError } = require('./fetch-error');
 const { HaltError } = require('./halt-error');
+const { RateLimitError } = require('./rate-limit-error');
 const {
     RequiredPropertyError,
     ParameterTypeError,
@@ -11,6 +12,7 @@ module.exports = {
     BaseError,
     FetchError,
     HaltError,
+    RateLimitError,
     RequiredPropertyError,
     ParameterTypeError,
     ClientSafeError,