Build it

Give each outside service a client with timeouts, add a retry helper with full jitter that only retries safe calls, wrap the SMS gateway in an opossum circuit breaker with a fallback, and pass a deadline through NestJS's HttpModule. The steps run in a Node project on your machine. The two core ideas, the full-jitter delay and the breaker's state machine, are exercises you can try in the browser in the Practice section below.

1. One axios client per dependency, each with a timeout

   Install npm i axios opossum and npm i -D @types/opossum. Separate clients let each dependency have its own timeout and its own breaker.

   TypeScriptCopy

   // http-client.ts
   import axios from 'axios';
   
   // One instance per dependency, each with its own timeout
   export const supplierApi = axios.create({
     baseURL: process.env.SUPPLIER_API_URL,
     timeout: 2000,          // no response within 2 s, or 2 s of silence: give up
   });
   
   export const smsApi = axios.create({
     baseURL: process.env.SMS_GATEWAY_URL,
     timeout: 2500,
   });
   
   // timeout alone does not stop a server that sends a byte every second.
   // AbortSignal.timeout() is a hard limit on the whole call, body included.
   export async function getPrice(articleId: number) {
     const res = await supplierApi.get<{ price: string }>(`/articles/${articleId}/price`, {
       signal: AbortSignal.timeout(3000),
     });
     return res.data.price;
   }

   A timed-out axios call throws an error with code: 'ECONNABORTED', or 'ETIMEDOUT' if you set transitional: { clarifyTimeoutError: true }. An aborted signal throws a CanceledError with code: 'ERR_CANCELED'.

2. A retry helper with full jitter

   It retries only errors that waiting can fix, only for safe methods or requests with an idempotency key, at most 3 attempts in total, and it respects Retry-After.

   TypeScriptCopy

   // retry.ts
   import axios from 'axios';
   
   const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
   const RETRY_STATUS = new Set([429, 502, 503, 504]);
   const RETRY_CODES = new Set(['ECONNABORTED', 'ETIMEDOUT', 'ECONNRESET', 'EAI_AGAIN']);
   const SAFE_METHODS = new Set(['get', 'head', 'options', 'put', 'delete']);
   
   export function isRetryable(err: unknown): boolean {
     if (!axios.isAxiosError(err)) return false;
     if (err.code === 'ECONNREFUSED') return true;            // never reached the server
     const method = (err.config?.method ?? 'get').toLowerCase();
     const safe = SAFE_METHODS.has(method) || !!err.config?.headers?.has('Idempotency-Key');
     if (!safe) return false;                                  // a POST may have worked already
     if (err.response) return RETRY_STATUS.has(err.response.status);
     return RETRY_CODES.has(err.code ?? '');                   // timeout or dropped connection
   }
   
   function retryAfterMs(err: unknown): number {
     const h = axios.isAxiosError(err) ? err.response?.headers['retry-after'] : undefined;
     if (!h) return 0;
     const secs = Number(h);                                   // "Retry-After: 2"
     if (!Number.isNaN(secs)) return secs * 1000;
     const at = Date.parse(String(h));                         // or an HTTP date
     return Number.isNaN(at) ? 0 : Math.max(0, at - Date.now());
   }
   
   export async function withRetry<T>(
     fn: () => Promise<T>,
     { attempts = 3, baseMs = 200, capMs = 5000 } = {},
   ): Promise<T> {
     for (let attempt = 0; ; attempt++) {
       try {
         return await fn();
       } catch (err) {
         if (attempt + 1 >= attempts || !isRetryable(err)) throw err;
         const ceiling = Math.min(capMs, baseMs * 2 ** attempt);   // 200, 400, 800 ... capped
         const wait = Math.random() * ceiling;                      // full jitter
         await sleep(Math.max(wait, retryAfterMs(err)));
       }
     }
   }

   TypeScriptCopy

   // usage
   const price = await withRetry(() => getPrice(1001));            // GET: safe to retry
   
   await withRetry(() =>                                            // POST: only with a key
     supplierApi.post('/purchase-orders', po, { headers: { 'Idempotency-Key': po.clientRef } }),
   );

3. See which calls get retried

   Against a test server that always answers 503, or never answers, the helper behaves like this (attempts counted on the server):

   OutputCopy

   GET  /x          -> 503 each time      attempts: 3, then throws
   POST /x, no key  -> 503                attempts: 1 (not safe to repeat)
   POST /x, key     -> 503 each time      attempts: 3
   GET  /hang       -> times out          attempts: 3, code ECONNABORTED

4. Wrap the SMS gateway in a circuit breaker with a fallback

   The fallback queues the receipt for later with BullMQ (see Queues, background jobs and pub/sub). The jobId is the same reference the gateway receives, so a receipt is never queued twice. Opossum's own timeout is a safety net above the axios timeout.

   TypeScriptCopy

   // sms.breaker.ts
   import axios from 'axios';
   import CircuitBreaker from 'opossum';
   import { Queue } from 'bullmq';
   import { Logger } from '@nestjs/common';
   import { smsApi } from './http-client';
   
   const log = new Logger('SmsBreaker');
   const smsRetryQueue = new Queue('sms', { connection: { host: 'localhost', port: 6380 } });
   
   async function sendSms(to: string, text: string, ref: string): Promise<{ id: string }> {
     const res = await smsApi.post('/messages', { to, text, clientRef: ref }, {
       headers: { 'Idempotency-Key': ref },
     });
     return res.data;
   }
   
   export const smsBreaker = new CircuitBreaker(sendSms, {
     timeout: 3000,                // opossum stops waiting after 3 s (axios gives up at 2.5 s)
     errorThresholdPercentage: 50, // open when half of the recent calls failed...
     volumeThreshold: 10,          // ...and there were at least 10 calls in the window
     rollingCountTimeout: 10_000,  // the window: the last 10 seconds
     resetTimeout: 30_000,         // stay open 30 s, then let one trial call through
     capacity: 20,                 // bulkhead: at most 20 calls in flight at once
     // A rejected phone number is our problem, not an outage: don't count it
     errorFilter: (err) => axios.isAxiosError(err) && err.response?.status === 400,
   });
   
   // Fallback: runs when the call fails, times out, or the circuit is open
   smsBreaker.fallback(async (to: string, text: string, ref: string) => {
     await smsRetryQueue.add('receipt', { to, text, ref }, { jobId: ref, delay: 60_000 });
     return { id: 'queued' };
   });
   
   smsBreaker.on('open', () => log.warn('SMS gateway circuit OPEN: failing fast'));
   smsBreaker.on('halfOpen', () => log.log('SMS gateway circuit HALF-OPEN: one trial call'));
   smsBreaker.on('close', () => log.log('SMS gateway circuit CLOSED: back to normal'));

   Checkout calls await smsBreaker.fire(phone, text, `receipt-${saleId}`) after the sale is saved. With a fallback set, fire() resolves with the fallback's value instead of rejecting, so checkout carries on. A filtered 400 is not counted against the breaker and does not trigger the fallback: fire() rejects with it, so handle it where you call fire(). In a test with the breaker set to open after 4 calls, the gateway received exactly 4 calls; the 5th and 6th were rejected with EOPENBREAKER in under a millisecond.

5. Set timeouts in NestJS's HttpModule and pass a deadline

   @nestjs/axios passes its options to axios, so timeout works the same way. The service turns the request's deadline into a per-call timeout, so a call never waits past the moment the user stops caring.

   TypeScriptCopy

   // payments.module.ts
   import { Module } from '@nestjs/common';
   import { HttpModule } from '@nestjs/axios';
   import { ConfigModule, ConfigService } from '@nestjs/config';
   import { PaymentsService } from './payments.service';
   
   @Module({
     imports: [
       HttpModule.registerAsync({
         imports: [ConfigModule],
         inject: [ConfigService],
         useFactory: (config: ConfigService) => ({
           baseURL: config.getOrThrow<string>('PAYMENT_API_URL'),
           timeout: 4000,            // passed straight to axios
           maxRedirects: 0,
         }),
       }),
     ],
     providers: [PaymentsService],
     exports: [PaymentsService],
   })
   export class PaymentsModule {}

   TypeScriptCopy

   // payments.service.ts
   import { Injectable, ServiceUnavailableException } from '@nestjs/common';
   import { HttpService } from '@nestjs/axios';
   import { firstValueFrom } from 'rxjs';
   
   export interface PaymentStatus { paymentId: string; status: 'PENDING' | 'PAID' | 'FAILED' }
   
   @Injectable()
   export class PaymentsService {
     constructor(private readonly http: HttpService) {}
   
     /** `deadline` is the time (ms since epoch) by which the whole checkout must answer. */
     async status(paymentId: string, deadline: number): Promise<PaymentStatus> {
       const left = deadline - Date.now();
       if (left < 200) throw new ServiceUnavailableException('No time left to ask the payment API');
       const res = await firstValueFrom(
         this.http.get<PaymentStatus>(`/payments/${paymentId}`, {
           timeout: Math.min(4000, left - 100),            // never wait past the caller's deadline
           headers: { 'X-Request-Deadline': String(deadline) },
         }),
       );
       return res.data;
     }
   }

   The controller sets the deadline once, for example const deadline = Date.now() + 5000, and passes it to every service call it makes. The called service can read X-Request-Deadline and do the same with the time that is left.