Don't Let Third-Party APIs Drag You Down: Timeouts, Circuit Breakers & Fallbacks for Vibe Projects

The day your vibe project goes live, everything feels perfect: users sign up, the model API generates content, Stripe collects payments, Resend sends welcome emails — all in one smooth flow. Then at 3 AM on some random Tuesday, the model API starts throwing intermittent 502s. Your server has no timeouts configured, so every request waits dumbly for 120 seconds; the frontend retries frantically, hammering an already half-dead upstream into the ground; users see spinners, errors, and duplicate charges. You crawl out of bed to check the bill and discover the retry storm burned through a week's worth of API quota.

This isn't hypothetical. It's a rite of passage for nearly every indie project that depends on third-party services. Vibe coding lets one person ship an entire product — but what you ship stands on other people's shoulders: model APIs, payments, email, object storage, auth services. Any one of them going down can drag you under with it. This guide skips the platitudes and covers four things: timeouts, retries, circuit breakers, and fallbacks — plus budget breakers, health probes, and monthly drills. Every section comes with code you can copy and numbers you can use.

1. First, See Clearly: How Many "Borrowed Pillars" Your Vibe Project Stands On

Before hardening anything, map your dependencies. A typical vibe project relies on these categories of third-party services:

Dependency	Common services	First symptom when it fails	Severity
Model API	OpenAI / Anthropic / Gemini / OpenRouter	Core features die outright; generation pages spin forever	★★★★★
Auth service	Clerk / Auth0 / Supabase Auth	Nobody can log in; existing users get kicked out	★★★★★
Payments	Stripe / Paddle / Lemon Squeezy	No revenue coming in, but existing features keep working	★★★★☆
Email	Resend / SendGrid / SES	Signup verification, password resets, notifications all break	★★★☆☆
Object storage	Cloudflare R2 / S3 / Alibaba Cloud OSS	Uploads fail, images break	★★★☆☆
Database / hosting	Supabase / Neon / Vercel / Railway	Entire site goes down	★★★★★

Here's a counterintuitive conclusion: for most vibe projects, the deadliest dependency isn't the model API — it's auth and the database. When the model API dies, users can at least browse and view their history; when auth dies, the front door is welded shut and nobody gets in. So prioritize your resilience work by "how much it hurts users when it breaks," not by "what feels important."

Field advice: take a sheet of paper (or a spreadsheet), list every third-party dependency, and write down what happens if each one is down for 5 minutes, 1 hour, or 1 day. You'll find at least one or two dependencies you never imagined could fail — those are usually the first to go.

2. The Four Layers of Resilience: Timeout > Retry > Circuit Breaker > Fallback

Resilience has four layers, and the order is non-negotiable:

1. Timeout: give every external call a deadline. Never wait forever.
2. Retry: absorb transient failures silently, invisibly to users.
3. Circuit breaker: when a downstream stays broken, cut it off deliberately instead of letting the failure cascade.
4. Fallback: when all else fails, give users a path forward instead of a 500 page.

Why can't the order be reversed? Because each layer is the prerequisite for the next:

• Without timeouts, retries become "queuing up to die" — ten requests each waiting 120 seconds will eat your connection pool first.
• Without a disciplined retry policy, the circuit breaker gets tripped by network jitter, downgrading your whole site over a hiccup.
• Without a circuit breaker, retries become a DDoS against your downstream — it's already struggling and you're "helping" it die faster with dozens of extra requests per second.
• Without fallbacks, an open circuit just means serving 500s directly, which captures only half the point of breaking the circuit.

Remember the chain: timeouts bound individual calls, retries absorb transient faults, circuit breakers stop failure from spreading, fallbacks protect the user experience. The next four sections make each layer concrete.

3. Timeouts: Three-Layer Rules — Give Every Call a Deadline First

Timeouts are the cheapest resilience measure with the highest return, yet most people set a single timeout and call it done. In reality, one HTTP call has three time layers, and each needs its own setting:

• Connect timeout: TCP handshake + TLS setup. If you can't connect in 3–5 seconds, the other side is probably gone; waiting longer is pointless.
• Read timeout: after connecting, how long to wait for the first byte / full response. Set 10–30s for ordinary APIs; streaming model APIs can go 60–120s, but only with the next rule in place.
• Overall timeout (deadline): total time from initiating the call to when you must return. This is the final insurance. Rule of thumb: slightly shorter than your own upstream budget. If your API runs on Vercel Hobby (10s) or Pro (60s), the overall timeout must be under that — otherwise the platform kills your function before your timeout logic ever runs.

Call type	Connect timeout	Read timeout	Overall timeout
Ordinary REST API (payments / email / auth)	3s	10s	15s
Model API (non-streaming)	5s	60s	90s
Model API (streaming SSE)	5s	120s (with heartbeat detection)	180s
Object storage upload	5s	60s	120s
Health-check probe	1s	2s	2s

In Node.js the cleanest approach is AbortController, supported by fetch, undici, and axios alike:

// fetchWithTimeout: add an overall timeout to any fetch call
export async function fetchWithTimeout(
  url: string,
  init: RequestInit & { timeoutMs?: number } = {},
): Promise<Response> {
  const { timeoutMs = 10_000, ...rest } = init;
  const controller = new AbortController();
  // Merge with a caller-provided signal if one exists
  const signals = [controller.signal, rest.signal].filter(Boolean) as AbortSignal[];
  const timer = setTimeout(() => controller.abort(
    new Error(`request timeout after ${timeoutMs}ms: ${url}`),
  ), timeoutMs);
  try {
    const res = await fetch(url, { ...rest, signal: AbortSignal.any(signals) });
    return res;
  } finally {
    clearTimeout(timer);
  }
}

One iron rule: never copy timeout values off the internet and use them blindly. Base them on your own P99 latency: read timeout ≈ P99 × 3, overall timeout ≈ read timeout × 1.5. Setting timeouts without looking at your latency distribution is driving blindfolded.

4. Retries: Exponential Backoff + Jitter, and 4 Scenarios Where You Must Never Retry

Retries are a double-edged sword: done right, users never notice; done wrong, you personally manufacture a DDoS. The standard practice is exponential backoff + jitter: wait exponentially longer each time, plus random jitter so all clients don't retry at the same instant and create a thundering herd.

// withRetry: the standard exponential-backoff-with-full-jitter implementation
export async function withRetry<T>(
  fn: () => Promise<T>,
  opts: {
    maxAttempts?: number;                    // total attempts including the first
    baseDelayMs?: number;                    // backoff base
    maxDelayMs?: number;                     // cap per wait
    retryOn?: (err: unknown) => boolean;      // which errors deserve a retry
  } = {},
): Promise<T> {
  const {
    maxAttempts = 4,
    baseDelayMs = 500,
    maxDelayMs = 8_000,
    retryOn = isRetryableError,
  } = opts;

  let lastError: unknown;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      lastError = err;
      if (!retryOn(err) || attempt === maxAttempts) throw err;
      // Full jitter: sleep = random(0, min(maxDelayMs, base * 2^attempt))
      const cap = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
      const sleepMs = Math.random() * cap;
      await new Promise((r) => setTimeout(r, sleepMs));
    }
  }
  throw lastError;
}

// Default "worth retrying" check: network errors, timeouts, 429, 5xx only
export function isRetryableError(err: unknown): boolean {
  if (err instanceof Error && err.name === "AbortError") return true; // timeout
  const status = (err as { status?: number })?.status;
  if (status === 429) return true;
  if (status !== undefined && status >= 500) return true;
  // No status usually means a network-layer error (DNS / ECONNRESET / TLS)
  return status === undefined;
}

But more important than "how to retry" is "when to never retry." In these 4 scenarios, even one retry is wrong:

1. 4xx client errors (except 429 and 408): a 400 means your parameters are wrong — retrying 100 times still gives 400, and you've helpfully hammered the downstream along the way. Same for 401/403.
2. Non-idempotent writes: charging a card, sending an SMS, creating an order. After a timeout you have no idea whether the other side executed it — blind retries mean duplicate charges. The correct pattern is "check, then re-issue": query status with an idempotency key, and only re-issue if it never executed.
3. 429s where you ignore Retry-After: getting rate-limited and retrying on your own schedule means fighting the rate limiter head-on. On a 429, read the Retry-After response header first and wait as instructed.
4. The circuit breaker is already open: covered in the next section. When the breaker says "stop hitting it," your retry logic must obey, or the breaker is decorative.

Three more disciplines for retries: cap total attempts (usually 3–4 including the first), cap total elapsed time (all retries combined must fit inside the overall timeout), and retry on the server side only (frontend retries stacked on backend retries multiply exponentially — pick one side).

5. Circuit Breaker: A Complete, Copy-Paste-Ready TypeScript Implementation

Retries handle the occasional hiccup; the circuit breaker handles "the other side is down, stop salting the wound." A breaker has three states — understand the state machine and you understand the breaker:

• CLOSED: normal state. Requests pass through while failures are counted.
• OPEN: failure count hit the threshold. The breaker opens; subsequent requests are rejected immediately (fail fast) without touching the downstream, giving it time to recover.
• HALF_OPEN: after being open for a while, a small number of probe requests are let through. If they succeed, back to CLOSED; if they fail, back to OPEN.

Below is a zero-dependency implementation you can drop straight into your project. Save it as lib/circuit-breaker.ts:

// lib/circuit-breaker.ts — zero-dependency breaker, works in Node and Edge Runtime
export type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";

export interface CircuitBreakerOptions {
  failureThreshold?: number;  // consecutive failures before opening (default 5)
  successThreshold?: number;  // consecutive successes in half-open before closing (default 2)
  resetTimeoutMs?: number;    // how long open before half-open probes (default 30s)
  onStateChange?: (from: CircuitState, to: CircuitState) => void;
}

export class CircuitBreaker {
  private state: CircuitState = "CLOSED";
  private failures = 0;
  private successes = 0;
  private nextAttemptAt = 0;

  constructor(private readonly opts: CircuitBreakerOptions = {}) {}

  get currentState(): CircuitState {
    return this.state;
  }

  private get failureThreshold() { return this.opts.failureThreshold ?? 5; }
  private get successThreshold() { return this.opts.successThreshold ?? 2; }
  private get resetTimeoutMs() { return this.opts.resetTimeoutMs ?? 30_000; }

  private transition(to: CircuitState) {
    const from = this.state;
    if (from === to) return;
    this.state = to;
    this.opts.onStateChange?.(from, to);
  }

  /**
   * Run fn. When the circuit is open, go straight to fallback (fail fast)
   * without touching the downstream. The fallback is the optional
   * degradation function — a breaker is only complete with one.
   */
  async exec<T>(
    fn: () => Promise<T>,
    fallback?: () => Promise<T> | T,
  ): Promise<T> {
    if (this.state === "OPEN") {
      if (Date.now() < this.nextAttemptAt) {
        if (fallback) return fallback();
        throw new Error("[circuit-breaker] circuit is OPEN, request rejected fast");
      }
      // Cooling period over — enter half-open probing
      this.transition("HALF_OPEN");
      this.successes = 0;
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (err) {
      this.onFailure();
      // This call just tripped the breaker open and a fallback exists:
      // degrade immediately instead of throwing
      if (this.state === "OPEN" && fallback) return fallback();
      throw err;
    }
  }

  private onSuccess() {
    this.failures = 0;
    if (this.state === "HALF_OPEN") {
      this.successes += 1;
      if (this.successes >= this.successThreshold) this.transition("CLOSED");
    }
  }

  private onFailure() {
    this.successes = 0;
    this.failures += 1;
    if (this.state === "CLOSED" && this.failures >= this.failureThreshold) {
      this.transition("OPEN");
      this.nextAttemptAt = Date.now() + this.resetTimeoutMs;
    } else if (this.state === "HALF_OPEN") {
      // Probe failed: back to OPEN, cooling restarts
      this.transition("OPEN");
      this.nextAttemptAt = Date.now() + this.resetTimeoutMs;
    }
  }
}

Usage is straightforward — wrap wherever you used to call the downstream directly:

import { CircuitBreaker } from "./lib/circuit-breaker";

const modelApiBreaker = new CircuitBreaker({
  failureThreshold: 5,
  resetTimeoutMs: 30_000,
  onStateChange: (from, to) =>
    console.warn(`[breaker:model-api] ${from} -> ${to}`), // wire into your alerting
});

export async function generateText(prompt: string): Promise<string> {
  return modelApiBreaker.exec(
    () => withRetry(() => fetchWithTimeout("https://api.example.com/v1/chat", {
      method: "POST",
      timeoutMs: 60_000,
      body: JSON.stringify({ prompt }),
    }).then((r) => {
      if (!r.ok) throw Object.assign(new Error(`upstream ${r.status}`), { status: r.status });
      return r.text();
    })),
    // Fallback: covered in detail next section; simplest version — serve cache
    () => getCachedGeneration(prompt),
  );
}

Notice how this wires the first three layers together: fetchWithTimeout bounds each call, withRetry absorbs transient jitter, and CircuitBreaker fails fast with a fallback when the outage persists. That's the "order is non-negotiable" principle in working code.

Tuning rules of thumb: failureThreshold 3–5 (too small and jitter trips it falsely; too large and the cascade is already underway); resetTimeoutMs 30–60s (too short and probe requests re-kill a just-recovering downstream); in HALF_OPEN let through exactly 1 probe request, not a crowd. The in-memory version covers 99% of vibe projects — you only need Redis-shared state for multi-instance deployments, which is a "tens of thousands of DAU" problem.

6. Fallback Paths: What Users See After the Breaker Opens

Opening the breaker only "stops the bleeding from getting worse"; fallbacks actually "stop the bleeding." The core question for fallback design is just one: with this dependency down, can users still achieve their core goal? Have the answer ready for each dependency before the outage:

Dependency failure	Fallback plan	What the user sees
Model API down	Serve semantic cache / last successful result; new requests enter a queue and auto-complete after recovery with a notification	"AI service is busy — you're queued and it will complete automatically" — not a spinner until timeout
Payment gateway down	Orders land in the DB first (status=pending) with an outbox pattern retrying the charge later; block duplicate submissions	"Payment channel under maintenance — order saved, will charge automatically"
Email service down	Verification codes/notifications switch to in-app messages + a status-page announcement; let critical flows (e.g. signup) proceed first and backfill emails later	In-app banner + inbox message instead of waiting on email that never comes
Object storage down	Reads served from CDN cache; writes go to a local temp dir with a background job syncing later	Old images display fine; new uploads say "try again later"
Auth service down	Extend existing session lifetimes (grace period); new logins queue up	Logged-in users unaffected

Three principles for fallback design:

1. Fallbacks are product decisions, not technical patches. "Show cached results when the model API is down" needs a product call: should cached results be labeled as historical? Can users cancel queued tasks? Decide before the outage, encode it in code — not at 3 AM mid-incident.
2. Fallback paths need their own timeouts and kill switches. Caches can fail too, queues can fill up. Give fallbacks even shorter timeouts and a manual master switch (feature flag) to disable a misbehaving fallback instantly.
3. Always tell users what's happening. The worst fallback is the silent one — users think it succeeded while the task was actually dropped. One honest "service temporarily unavailable, you're queued" beats ten loading spinners.

7. Budget Breaker: Don't Let the API Bill "Trip" You First

So far we've covered "what if the service goes down." There's a sneakier way to die: the service is fine, but your money is gone. The classic vibe-project script: a prompt written too long, a loop bug hammering the model API, or a malicious user scraping your endpoints — you wake up to a bill with an extra zero. Provider-side usage quotas help somewhat, but they're account-level and laggy; by the time the email arrives, the money is spent.

So your wallet needs a breaker too — the budget breaker:

• Daily/monthly budget caps: set per external service. Model APIs get a daily spend cap (e.g. $20/day); when breached, auto-downgrade to a cheaper model or queue requests instead of burning the flagship model.
• Velocity alerts: an earlier signal than "over budget" is "spending too fast." If the last hour's spend exceeds 5× the trailing 7-day average for the same hour, alert immediately — that's usually a bug or an attack, not organic growth.
• Graduated breaker actions: tier one is alerting (Slack / email / SMS); tier two is auto-degradation (switch to cheaper models, disable non-core AI features); tier three is the kill switch (halt all non-essential calls). Don't start with the kill switch and nuke legitimate users.

Implementation is simple at its core — just a counter. Check it before every call:

// lib/spend-guard.ts — spend breaker: check before calling, degrade past budget
import { redis } from "./redis";

export async function spendGuard(
  service: string,            // "openai" / "anthropic" ...
  estimatedCostUsd: number,   // estimated cost of this call (estimate from token count)
): Promise<boolean> {
  const day = new Date().toISOString().slice(0, 10);
  const key = `spend:${service}:${day}`;
  const spent = await redis.incrbyfloat(key, estimatedCostUsd);
  await redis.expire(key, 86400 * 2); // keep keys two days for reconciliation

  const budget = Number(process.env[`${service.toUpperCase()}_DAILY_BUDGET_USD`] ?? 20);
  if (spent > budget) {
    await alert(
      `Budget breaker: ${service} spent $${spent.toFixed(2)} today, over the $${budget} cap — auto-degraded`,
    );
    return false; // callers seeing false take the fallback path
  }
  // Velocity alert: this hour's spend vs. historical norm (simplified; use a
  // sliding window in production)
  const hourKey = `spend:${service}:${day}:${new Date().getHours()}`;
  const hourSpent = await redis.incrbyfloat(hourKey, estimatedCostUsd);
  await redis.expire(hourKey, 7200);
  if (hourSpent > budget * 0.5) {
    await alert(`Abnormal spend velocity: ${service} spent $${hourSpent.toFixed(2)} this hour`);
  }
  return true;
}

// Caller: one line to integrate
export async function generateText(prompt: string) {
  const ok = await spendGuard("openai", estimateCost(prompt));
  const model = ok ? "gpt-5" : "gpt-5-mini"; // auto-downgrade past budget
  // ... normal call
}

Hard-won lesson: overestimate costs rather than underestimate; a false downgrade beats a real overrun. Users at worst feel "the AI is a bit dumb today"; an overrun means you worked this month for free. And put budget numbers in environment variables, never hardcode them — editing code and redeploying at midnight to adjust a budget is miserable.

8. Health-Check Probes: One /health Endpoint Watching Every Downstream

Everything so far is "when failure strikes." This section is "spot it early." You need a /health endpoint that your monitoring (Uptime Kuma, Better Stack) pings every minute and that shows at a glance which downstream is unhealthy.

Probe design has three requirements: fast (must return within 2 seconds, or the probe itself times out), light (minimal-cost checks only — never trigger real billable operations), and honest (return 503 if any dependency is unhealthy; no sugarcoating).

// app/api/health/route.ts — Next.js App Router health probe example
import { NextResponse } from "next/server";

type CheckResult = { name: string; ok: boolean; latencyMs: number; error?: string };

async function runCheck(
  name: string,
  fn: () => Promise<unknown>,
  timeoutMs = 1500,
): Promise<CheckResult> {
  const start = Date.now();
  try {
    await Promise.race([
      fn(),
      new Promise((_, reject) =>
        setTimeout(() => reject(new Error("probe timeout")), timeoutMs),
      ),
    ]);
    return { name, ok: true, latencyMs: Date.now() - start };
  } catch (err) {
    return {
      name, ok: false, latencyMs: Date.now() - start,
      error: err instanceof Error ? err.message : String(err),
    };
  }
}

export async function GET() {
  const checks = await Promise.all([
    runCheck("database", () => db.query("SELECT 1")),                       // lightest DB probe
    runCheck("model-api", () =>                                           // list models, no billing
      fetchWithTimeout("https://api.example.com/v1/models", { timeoutMs: 1500 })
        .then((r) => { if (!r.ok) throw new Error(`status ${r.status}`); })),
    runCheck("storage", () => storage.headBucket()),                       // HEAD only, no read/write
    runCheck("queue", () => redis.ping().then((p) => {                     // also glance at queue depth
      if (p !== "PONG") throw new Error("redis ping failed");
    })),
  ]);
  const allOk = checks.every((c) => c.ok);
  return NextResponse.json(
    { status: allOk ? "ok" : "degraded", checks, timestamp: new Date().toISOString() },
    { status: allOk ? 200 : 503 },
  );
}

Details that decide whether the probe is actually useful:

• Probe model APIs via metadata endpoints like /v1/models, never a real generation request — one real call per minute is 40,000+ billable calls a month, burned for nothing.
• Wire probe results into alerting: the monitor notifies you on 503. An endpoint nobody watches is the same as no endpoint.
• Add a "deep mode": /health?deep=1 runs heavier checks (e.g. write-then-delete a test row). Unused normally; invoked manually when debugging.
• Protect the probe itself: each check gets its own timeout and they run concurrently via Promise.all — one hung downstream must not stall the whole probe.

9. Drill SOP: Break One Dependency by Hand, Once a Month

No matter how good the code is, untested resilience is unwritten resilience. Netflix has Chaos Monkey; you don't need that — 30 minutes a month "turning off one dependency" is enough for a vibe project. The standard flow:

1. Pick a target: which dependency this month? Rotate through the section-1 table starting from the most critical: model API, auth, payments, email, storage — one per month.
2. Write down expectations first: "I expect the breaker to open within 30 seconds, users to see the queue notice, and alerts to arrive within 1 minute." Written expectations enable comparison; otherwise you'll just walk away thinking "seemed fine."
3. Break it in staging: point that dependency's endpoint at a black hole (timeout) or a hard 500 via env var or feature flag. No staging? Do it in production off-peak, but only "read-only" drills (e.g. drop the read timeout to 1s and observe) — never actually kill payments.
4. Watch three things: did the breaker open as expected? Did users see the fallback notice or a 500? Did alerts fire — how many, and were there false positives?
5. Recover and time it: "fix" the dependency and measure how long until the breaker closes and service is fully normal. That duration is your real RTO.
6. Log one lesson: one most-valuable finding per drill, into the project's resilience-notes.md. Twelve months of this gives you your own incident handbook.

Start your first drill with "email service down" — smallest blast radius, and you'll see the full breaker → fallback → alert chain. Don't start with payments on drill one; your heart can't take it.

10. Anti-Patterns: 5 Classic Ways to Shoot Yourself in the Foot

1. Blind retries with no backoff or cap. The most common death: frontend setInterval retrying every 2s plus backend retries, multiplying request volume exponentially during an outage. Retries must have backoff, jitter, a total cap — and live on the server side only.
2. One timeout config for every dependency. Applying the model API's 60s timeout to the payment gateway means a hung payment provider eats your connection pool just the same. Configure each dependency independently, in environment variables.
3. A breaker with no fallback. When the breaker opens and just throws 500s, the user experience is as bad as having no breaker — only your server survives. The other half of breaking is degrading: the second argument of exec(fn, fallback) isn't optional decoration, it's a required answer.
4. "Heavy" health checks. Probes that run real model generations or send real test emails every minute burn money and can trip providers' abuse detection. Probes do metadata-level checks only; heavy checks belong in manual deep mode.
5. Resilience that exists only in code, with zero alerting and zero drills. The breaker opened and nobody knew; the budget blew and nobody knew; the fallback ran for three months and nobody knew — until users complained. Every state change needs logs and alerts; every month needs a hands-on drill. Untested resilience code is just a security blanket.

Do These Three Things First (Shippable This Week)

If you're thinking "all true, but where do I start" — in this order, each about half a day of work:

1. Put timeouts on every external call: copy fetchWithTimeout into your project and replace bare fetch calls globally. The highest-ROI single change you can make.
2. Breaker + minimal fallback for the model API: copy the CircuitBreaker from section 5; start the fallback with the simplest honest version — "AI service is busy, please try again later" beats a spinner. Add cached degradation and queuing later.
3. Build the /health endpoint and hook up monitoring: self-host Uptime Kuma (5 minutes) or use Better Stack's free tier, pinging every minute. Next outage, you'll know before your users do.

Third-party dependencies won't go away — they'll only multiply. Vibe coding gave one person the output of an entire team; resilience design gives one person the on-call capability of an entire team. Dependencies will fail, bills will spike, and the 3 AM alert will ring — the only difference is whether you're the protagonist who wrote the script in advance, or a spectator getting dragged under.