API Integration

The employees API does not change when a phone calls it. Everything around the call does. On a server, a request to another service travels over a stable link with predictable latency; on a device it travels over a radio whose quality depends on where the user is standing.

So the code that calls your API from a device needs things the server-side equivalent can often do without: a timeout on every request, a considered retry policy, the ability to cancel work the user no longer wants, and a real answer for what the screen shows when none of it succeeds.

Put all of that in one place. A single module that every screen goes through is how you guarantee no call ships without a timeout. Scatter fetch calls across twenty screens and at least one of them will hang forever, on a connection you cannot reproduce.

export class HttpError extends Error {
  constructor(readonly status: number) {
    super("HTTP " + status);
  }
}

export class OfflineError extends Error {}

/** One place owns timeouts, so no call site can forget one. */
export async function getJson<T>(
  url: string,
  callerSignal: AbortSignal,
  timeoutMs = 10000,
): Promise<T> {
  const timeout = new AbortController();
  const timer = setTimeout(() => timeout.abort(), timeoutMs);

  try {
    const response = await fetch(url, {
      signal: AbortSignal.any([callerSignal, timeout.signal]),
      headers: { Accept: "application/json" },
    });

    if (!response.ok) throw new HttpError(response.status);

    const type = response.headers.get("content-type") ?? "";
    if (!type.includes("application/json")) {
      throw new OfflineError("Expected JSON. A network may be intercepting.");
    }

    return (await response.json()) as T;
  } finally {
    clearTimeout(timer);
  }
}

• The shape is what transfers. Your platform's HTTP client will spell cancellation differently — a cancellation token, a disposable subscription, a call object you cancel — and the structure stays the same: a caller-owned cancellation, a timeout you create, and both able to stop the request.
• Ten seconds is a starting point, not a rule. A list the user is waiting on should give up sooner, around five to eight seconds, because past that they have concluded it is broken. A background upload can afford much longer. The unacceptable value is no timeout at all, which is the default in more clients than you would expect.
• The caller's signal is how a screen cancels its own work. When the user navigates away, the screen aborts, the request stops, and the radio stops being used for an answer nobody wants. Without it you pay battery for a response you will discard.
• The content type check catches the captive portal case. A sign-in page returned with a 200 status looks like success to your code and then fails inside JSON parsing with a message about unexpected characters, which is a confusing thing to show a user and a worse thing to debug from a crash report.
• The finally clause clears the timer on every path, including cancellation. A leaked timer that fires later aborts a controller nobody is using, which is harmless here and exactly the kind of loose end that becomes harmful once this function grows.

const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);

function isWorthRetrying(error: unknown): boolean {
  if (error instanceof HttpError) return RETRYABLE_STATUSES.has(error.status);
  // A transport failure: the request never got an answer.
  return error instanceof TypeError || error instanceof OfflineError;
}

const delay = (ms: number) => new Promise((done) => setTimeout(done, ms));

export async function withRetry<T>(
  call: () => Promise<T>,
  attempts = 3,
): Promise<T> {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    try {
      return await call();
    } catch (error) {
      const lastAttempt = attempt === attempts - 1;
      if (lastAttempt || !isWorthRetrying(error)) throw error;

      const base = 500 * 2 ** attempt; // 500ms, then 1s, then 2s
      const jitter = Math.random() * base * 0.3;
      await delay(base + jitter);
    }
  }
  throw new Error("unreachable");
}

• Again, read the structure rather than the API. Most platforms have a retry helper somewhere; what matters is that the decision about what to retry is written down once and is specific about it.
• The backoff doubles. Retrying immediately three times on a weak connection is three failures in under a second, which helps nobody and keeps the radio awake. Waiting 500ms, then a second, then two gives the connection a chance to actually come back.
• The jitter is not decoration. Without it, every device that lost connectivity at the same moment retries at the same moment, and a server recovering from an incident is hit by a synchronised wave. A random spread of up to thirty percent is enough to break that up.
• Three attempts and a cap on the total wait is deliberate. Retrying indefinitely on a device drains the battery and hides the problem from the user, who would rather be told there is no connection than watch a spinner for two minutes.
• The classification is the important line in this sample. A 404 or a 422 will fail identically every time, so retrying it wastes power and delays an honest message. A 503 or a dropped connection may well succeed a second later. Note also that 429 means the server is asking you to slow down, and if it sends a Retry-After header, honouring that value takes precedence over your own backoff.