DEV Community: Mohamad Reza Rajabi

From Contract Boundary to Error Boundary: Structuring API Error Handling in a TypeScript Frontend

Mohamad Reza Rajabi — Sun, 06 Sep 2026 12:38:31 +0000

In a previous post, I covered why TypeScript types alone can't protect you from a backend that returns something you didn't expect, and how to build a small apiRequest boundary that validates both the outgoing request and the incoming response against Zod-style schemas before your application ever touches the data.

That post answered one question:

Is this data actually shaped the way I think it is?

It left another question open:

When the answer is no, or when the request fails for a completely different reason (like a timeout or a dropped connection), what does the rest of the app do with that failure?

In practice, "the rest of the app" usually does something different depending on who's writing it:

One component checks error.response?.status directly.
Another checks error.code === "ECONNABORTED".
A form manually digs through the error to find field-level messages.
A toast just displays whatever string happens to be on error.message.

The app works, but every layer speaks a different error dialect. This post is Part 2: it takes the validation boundary from Part 1 and builds the missing piece on top of it, a single, normalized ApiError shape that every layer of the app can speak, plus the logging, messaging, and form-mapping that make it actually usable.

Quick Recap: The Validation Boundary

From Part 1, the apiRequest wrapper validates request payloads and response bodies against schemas, and throws one of two typed errors when something doesn't match the contract:

export class ApiRequestValidationError extends Error {
  constructor(public readonly url: string, public override readonly cause: unknown) {
    super(`API request input does not match the contract for ${url}.`);
    this.name = "ApiRequestValidationError";
  }
}

export class ApiResponseValidationError extends Error {
  constructor(public readonly url: string, public override readonly cause: unknown) {
    super(`API response does not match the contract for ${url}.`);
    this.name = "ApiResponseValidationError";
  }
}

ApiRequestValidationError means the frontend built a bad request. ApiResponseValidationError means the backend returned something that doesn't match its own contract. Every call site declares its schemas up front:

const project = await apiRequest({
  client: apiClient,
  method: "GET",
  url: `/projects/${id}`,
  responseSchema: projectSchema,
});

That's the whole boundary. Full details are in Part 1. What it doesn't cover is what happens after one of these errors is thrown, or after Axios itself fails for a reason that has nothing to do with schemas (a timeout, a cancelled request, a 500 from the server). That's where this post picks up.

The Core Idea: One Error Shape, One Boundary

The fix is to stop letting UI components see raw Axios errors, raw validation errors, or raw exceptions at all. Failures are translated into a common error model before reaching UI consumers: transport failures and HTTP error responses are normalized by the Axios interceptor, while the contract validation errors from Part 1 are converted into the same ApiError shape by explicitly calling normalizeApiError at the call site (since they're thrown directly by apiRequest, not by Axios, so the interceptor never sees them). Either path lands on the same predictable type:

export type ApiSubError = {
  field?: string;
  message: string;
  code?: string;
};

export type ApiError = {
  status: number | null;
  message: string;
  errors: ApiSubError[];
  fieldErrors: Record<string, string>;
  traceId: string | null;
  code: string | null;
};

No matter whether the failure was a 500 from the server, a timeout, a cancelled request, or a response that didn't match the schema from Part 1, it comes out the other side as an ApiError. Components, forms, and toasts only ever need to understand this one shape.

Step 1: Normalizing Everything at the Axios Interceptor

Schema-validation failures are one category. Network errors, timeouts, and HTTP error responses are another, and they come from Axios itself. Rather than handling these ad hoc in every catch block, a single response interceptor converts all of them into the same ApiError:

export function setupErrorInterceptor(apiClient: AxiosInstance) {
  apiClient.interceptors.response.use(
    (response) => response,
    (error) => Promise.reject(normalizeApiError(error)),
  );
}

The flow becomes:

Inside normalizeApiError, each failure mode is identified and classified before being converted:

export function normalizeApiError(error: unknown): ApiError {
  if (isApiError(error)) return error; // already normalized upstream

  if (axios.isAxiosError(error)) {
    const status = error.response?.status ?? null;
    const endpoint = error.config?.url ?? null;
    const method = error.config?.method ?? null;
    const code = error.code ?? "API_ERROR";

    if (axios.isCancel(error) || error.code === "ERR_CANCELED") {
      reportClientError({ kind: "api_request_cancelled", endpoint, method, status, code, message: error.message });
    } else if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
      reportClientError({ kind: "api_timeout", endpoint, method, status, code, message: error.message });
    } else if (!error.response) {
      reportClientError({ kind: "api_network_error", endpoint, method, status, code, message: error.message });
    }

    // ... validate and unwrap error.response.data (see next section)
  }

  if (error instanceof Error) {
    const isValidationError =
      error instanceof ApiRequestValidationError || error instanceof ApiResponseValidationError;

    if (!isValidationError) {
      reportClientError({ kind: "unknown_client_error", code: "UNKNOWN_ERROR", message: error.message });
    }

    return createApiError({ status: null, message: error.message, code: "UNKNOWN_ERROR" });
  }

  // Non-Error throws (string, undefined, etc.) still get a safe fallback
  reportClientError({ kind: "unknown_client_error", code: "UNKNOWN_ERROR", message: "A non-Error value was thrown." });
  return createApiError({ status: null, message: "Something went wrong", code: "UNKNOWN_ERROR" });
}

Notice the early isApiError(error) check: if something upstream already normalized the error (for example if a hook wraps apiRequest and re-throws), we don't re-process it. This makes normalizeApiError idempotent, which matters once you have interceptors, hooks, and query libraries (React Query, SWR) all potentially touching the same error object.

Step 2: Error Responses Are External Data Too, Validate Them

Here's the part that's easy to skip: we usually validate successful API responses, but the error body coming back from the backend is just as much untrusted external data. The contract for that envelope is just another Zod schema:

export const apiErrorItemSchema = z.object({
  code: z.string(),
  field: z.string().nullable(),
  message: z.string(),
});

export const apiErrorResponseSchema = z.object({
  success: z.literal(false),
  message: z.string(),
  errors: z.array(apiErrorItemSchema),
  traceId: z.string().uuid(),
});

A couple of details here are deliberate. field is nullable() rather than optional: an item that isn't tied to a specific input (a general "this operation isn't allowed" error) still has to explicitly say field: null, rather than silently omitting the key. And traceId is validated as a real UUID, not just any string, since it's what ties a user-facing error back to a specific log entry on the backend.

This pairs with a matching schema for successful responses, so both sides of every API call follow the same envelope shape:

export function successResponseSchema<T extends z.ZodType>(dataSchema: T) {
  return z.object({
    success: z.literal(true),
    message: z.string(),
    data: dataSchema,
  });
}

success: true vs success: false is a discriminant: given a raw response, you can tell which shape you're looking at before you've even touched the rest of the payload.

So a well-formed error envelope from the backend looks like this:

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    { "code": "EMAIL_ALREADY_EXISTS", "field": "email", "message": "Email already exists" }
  ],
  "traceId": "9f3a2b91-4c1e-4a3d-9f2a-7e6b1d0c8f45"
}

Or, because of a proxy, a gateway timeout, or a misconfigured endpoint, it might return something completely different:

{ "error": "Internal failure" }

Both are "errors" from Axios's point of view, but only one of them matches the contract and is safe to trust. So before building an ApiError from the response body, it gets parsed against the schema:

const envelopeResult = apiErrorResponseSchema.safeParse(error.response?.data);

if (envelopeResult.success) {
  const envelope = envelopeResult.data;

  if (status !== null && status >= 500) {
    reportClientError({
      kind: "api_server_error",
      endpoint, method, status, code,
      traceId: envelope.traceId,
      message: envelope.message,
    });
  }

  return createApiError({
    status,
    message: envelope.message,
    errors: envelope.errors,
    traceId: envelope.traceId,
  });
}

// The body didn't match the expected contract, don't trust it
if (error.response) {
  reportClientError({
    kind: "malformed_api_error_response",
    endpoint, method, status, code,
    issues: getValidationIssues(envelopeResult.error),
    message: error.message,
  });
}

return createApiError({ status, message: error.message || "Request failed.", code });

If the shape doesn't match, we don't try to guess at data.error or data.msg. We fall back to a generic message and flag it internally as malformed_api_error_response. This is the difference between "the backend told us the email is taken" (trustworthy, safe to show verbatim) and "something came back that we don't understand" (never shown verbatim to a user).

Step 3: Keeping Technical Detail Away From Users

"Network Error" and "Request failed with status code 500" are useful to a developer reading logs. They mean nothing to a user, and showing them erodes trust in the product. So there's a translation layer between ApiError and what actually renders:

export function getApiErrorMessage(error: unknown) {
  if (!isApiError(error) || !error.traceId) {
    return fallbackErrorMessage;
  }

  const translatedMessage = error.code ? apiErrorMessages[error.code] : undefined;

  if (translatedMessage) {
    return translatedMessage;
  }

  return error.message;
}

The rule here is deliberate:

Only errors that carry a traceId (meaning they came from our own validated backend envelope, not from an unknown or malformed source) are allowed to expose their message directly.

Everything else (network failures, malformed responses, unhandled exceptions) gets a generic fallback. This closes off an entire class of "leaking implementation details to the UI" bugs.

On top of that, specific backend error codes get mapped to friendly, localized copy:

const apiErrorMessages: Readonly<Record<string, string>> = {
  PROJECT_NOT_FOUND: "This project no longer exists or you don't have access to it.",
  PROJECT_REVISION_CONFLICT: "This project has changed. We've loaded the latest version, please review again.",
  EMAIL_ALREADY_EXISTS: "An account with this email already exists.",
  // ...
};

This is also a natural place to hang i18n: swap the dictionary per locale and every error message in the app updates without touching a single component.

Step 4: Mapping Backend Validation Errors Into Forms

This is where the structured model really pays off. A backend field error shouldn't turn into a generic toast; it should land right next to the input that caused it:

export function applyApiFormErrors<T extends FieldValues>(
  error: unknown,
  setError: UseFormSetError<T>,
  options: { fieldMap?: Partial<Record<string, Path<T> | null>>; formFields: readonly Path<T>[] },
) {
  if (!isApiError(error)) {
    return { apiError: null, fieldErrors: {}, message: fallbackErrorMessage };
  }

  const fieldMap = options.fieldMap ?? {};
  const formFields = new Set<string>(options.formFields);
  const mappedFieldErrors: Record<string, string> = {};

  for (const [field, message] of Object.entries(error.fieldErrors)) {
    const hasExplicitMapping = Object.prototype.hasOwnProperty.call(fieldMap, field);
    const mappedField = hasExplicitMapping ? fieldMap[field] : (field as Path<T>);

    if (!mappedField || !formFields.has(mappedField)) continue;

    mappedFieldErrors[mappedField] = message;
    setError(mappedField, { type: "server", message });
  }

  return { apiError: error, fieldErrors: mappedFieldErrors, message: getApiErrorMessage(error) };
}

Two details matter here:

fieldMap decouples backend field names from frontend field names. If the backend calls it identifier but the form calls it email, you map it once: fieldMap: { identifier: "email" }. Forms don't need to know about backend naming conventions.
formFields acts as an allowlist. If the backend returns an error for a field the form doesn't render, it's silently dropped instead of throwing or getting attached to a non-existent input.

Usage in a component ends up almost boring, which is the point:

try {
  await apiRequest({ /* ... create account ... */ });
} catch (error) {
  const apiError = normalizeApiError(error);
  const { message } = applyApiFormErrors(apiError, setError, {
    formFields: ["email", "password", "confirmPassword"],
    fieldMap: { identifier: "email" },
  });
  toast.error(message);
}

The component doesn't know or care whether the failure was a validation error, a conflict, or a network issue. It just calls one function and gets field-level errors plus a safe display message.

Step 5: Sanitizing Before You Log Anything

Debugging needs logs, but logs are also a common place for secrets to leak. Every error report goes through sanitization before it touches console.error:

function sanitizeText(value: string) {
  return value
    .replace(/\bBearer\s+\S+/gi, "Bearer [REDACTED]")
    .replace(
      /\b(password|newPassword|confirmPassword|accessToken|refreshToken|token|cookie|authorization|csrfToken|otp|authenticationCode)\s*[:=]\s*\S+/gi,
      "$1=[REDACTED]",
    )
    .replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, "[REDACTED]")
    .replace(/\+?\d[\d\s()-]{8,}\d/g, "[REDACTED]")
    .slice(0, 500);
}

A few things worth calling out:

Tokens (Bearer xyz...) get masked with a regex targeting the Authorization header format specifically.
Key-value patterns covering passwords, tokens, cookies, and OTPs are redacted regardless of casing or which object they came from. This catches things accidentally serialized into an error message, not just structured fields.
Emails and phone numbers are stripped with pattern matching, since these often show up embedded in validation messages ("email test@example.com is already taken").
A hard length cap (.slice(0, 500)) prevents a single runaway error message (say, a giant stack trace or a reflected payload) from flooding the console or a log aggregator.

The endpoint itself is also stripped of query strings before logging, since query params frequently carry tokens or PII:

function sanitizeEndpoint(endpoint: string | null | undefined) {
  if (!endpoint) return null;
  return sanitizeText(endpoint.split(/[?#]/, 1)[0] ?? "");
}

And the whole reporting function is guarded so that a bug in logging can never break the actual error-handling flow, and only runs in development:

export function reportClientError(report: ClientErrorReport) {
  if (process.env.NODE_ENV !== "development") return;

  const safeReport = {
    kind: report.kind,
    endpoint: sanitizeEndpoint(report.endpoint),
    method: report.method?.toUpperCase() ?? null,
    status: report.status ?? null,
    code: report.code ? sanitizeText(report.code) : null,
    traceId: report.traceId ? sanitizeText(report.traceId) : null,
    message: report.message ? sanitizeText(report.message) : null,
    // ...issues, sanitized the same way
  };

  try {
    if (warningKinds.has(report.kind)) {
      console.warn("[api-client]", safeReport);
      return;
    }
    console.error("[api-client]", safeReport);
  } catch {
    // Logging must never affect the application's actual error flow.
  }
}

In production this becomes a no-op by default. Swap it for a real telemetry sink (Sentry, Datadog, your own endpoint) behind the same interface, and every call site in the app is already wired up correctly.

Putting It All Together: A Signup Form

Here's how the validation boundary from Part 1 and the five pieces above compose in a realistic flow: a signup form that can fail from bad input, a duplicate email, or a dropped connection.

function useSignup() {
  const { setError } = useFormContext<SignupForm>();

  return async (data: SignupForm) => {
    try {
      const result = await apiRequest({
        client: apiClient,
        method: "POST",
        url: "/auth/signup",
        data,
        requestSchema: signupRequestSchema,
        responseSchema: signupResponseSchema,
      });

      return { success: true, result };
    } catch (error) {
      const apiError = normalizeApiError(error);
      const { message } = applyApiFormErrors(apiError, setError, {
        formFields: ["email", "password", "confirmPassword"],
      });

      toast.error(message);
      return { success: false };
    }
  };
}

Trace what happens for three different failures:

User submits an invalid email format → caught client-side by requestSchema, thrown as ApiRequestValidationError, normalized to a generic ApiError with no traceId → form gets no field errors (it's a client bug, not a backend rejection) → toast shows the fallback message. In development, reportClientError logs the exact Zod issue paths so you can fix the schema mismatch immediately.
Backend rejects because the email is taken → Axios error with a 409 and a valid error envelope → normalizeApiError parses the envelope, builds an ApiError with traceId and fieldErrors: { email: "..." } → applyApiFormErrors calls setError("email", ...) → the message under the email field shows apiErrorMessages.EMAIL_ALREADY_EXISTS, not the raw backend string.
The user's wifi drops mid-request → Axios error with no error.response → classified as api_network_error, logged for debugging → ApiError has traceId: null → getApiErrorMessage returns the safe fallback, since we don't trust an error with no trace as a "known" backend message.

One function call per layer, and the component never has to know which of these three happened.

Why This Is Worth the Extra Code

None of this is complicated in isolation: a type, an interceptor, a couple of try/catch blocks, some regexes. The value is in consistency: every failure in the app, no matter where it originates, ends up as the same ApiError shape by the time it reaches a component. That means:

New developers don't need to learn a different error-handling idiom for every failure mode scattered across the codebase; they learn one shape.
Forms, toasts, and logging all consume the same normalized data, so adding a new UI surface for errors (a banner, a modal) doesn't require re-deriving error logic.
Backend contract changes fail loudly and immediately (schema validation) instead of silently producing undefined three renders later.
Sensitive data has exactly one choke point to sanitize, instead of being a concern every developer has to remember at every console.log.

Errors are not an edge case you handle once and forget. In any application that talks to a real backend, they're a first-class part of the architecture, and treating them that way, with the same rigor you'd apply to success responses, pays off the moment the app grows past "one component, one try/catch."

Together with the validation boundary from Part 1, this gives the frontend two matching guarantees: data crossing into the app is verified before anything touches it, and data crossing into the UI as a failure is normalized before anything renders it. Runtime contracts on the way in, a structured error model on the way out.

TypeScript Types Are Not Enough: Building a Runtime API Contract Boundary

Mohamad Reza Rajabi — Tue, 01 Sep 2026 09:15:40 +0000

TypeScript gives us a lot of confidence.

We define types, interfaces, and function signatures. Our editor helps us catch mistakes before we even run the application.

But there is one important place where TypeScript cannot protect us:

Data coming from outside our application.

API responses are runtime data.

The backend can change. A field can be missing. A value can have a different type. An unexpected response can reach our frontend.

And TypeScript will not warn us.

The TypeScript Safety Illusion

Imagine we have a simple user type:

type User = {
  id: string;
  name: string;
};

Then we fetch a user:

const response = await fetch("/api/user");

const user = await response.json() as User;

Everything looks fine.

The editor is happy.
The build passes.

But what if the API returns:

{
  "id": 123
}

The problem is that TypeScript does not validate runtime values.

The as User syntax does not check anything. It only tells TypeScript:

"Trust me, this data has this shape."

But external data should not be trusted by default.

A Real Failure Scenario

Imagine we have a login endpoint.

Today, the backend returns:

{
  "accessToken": "abc123",
  "user": {
    "id": "1",
    "name": "John"
  }
}

The frontend has a matching type:

type LoginResponse = {
  accessToken: string;
  user: User;
};

Everything works.

But later, the backend changes the response:

{
  "token": "abc123",
  "user": {
    "id": "1",
    "name": "John"
  }
}

The application still builds successfully.

The bug appears later:

session.accessToken

becomes:

undefined

The problem is not TypeScript.

The problem is that the application accepted external data without verifying the contract.

API Responses Are Untrusted Data

A useful way to think about APIs is:

Before data enters our application, we should verify that it matches the contract we expect.

This is where runtime validation becomes useful.

The Simple Approach

A common approach is validating responses manually:

const response = await axios.get("/users");

const user = userSchema.parse(response.data);

This works.

But as the application grows, we start repeating the same pattern everywhere:

login()
logout()
getProfile()
getOrders()
updateUser()
...

Every API call needs:

request validation
response validation
error handling

At some point, validation itself becomes something that needs structure.

Creating an API Contract Boundary

Instead of validating every request manually, I created a small API wrapper responsible for this boundary.

The idea is simple:

The API layer receives schemas for both sides:

type ApiRequestOptions<TResponse, TData> = {
  requestSchema?: ApiSchema<TData>;
  responseSchema: ApiSchema<TResponse>;
};

Now API calls can define their contracts explicitly:

apiRequest({
  client,
  method: "post",
  url: "/staff/auth/login",
  data: payload,
  requestSchema: adminLoginSchema,
  responseSchema: adminLoginResponseSchema,
});

The feature does not need to know how validation happens.

It only defines the contract.

Keeping Contracts In A Shared Validation Layer

One important part of this approach is where the contracts live.

Instead of defining request and response shapes separately inside every feature, schemas are kept in a shared validation package.

For example:

import {
  adminLoginSchema,
  adminLoginResponseSchema,
} from "@app/validations/admin/auth";

Now the API call and the validation rules stay connected.

The API layer does not guess the shape of the data.

The contract defines it.

What The Boundary Actually Looks Like

Usually, we only think about validating responses.

But requests can be invalid too:

wrong field name
missing required value
incorrect format

Catching these problems before sending the request saves a round trip and makes the issue obvious immediately.

A simplified version of the API boundary looks like this:

async function apiRequest<TResponse, TData = unknown>({
  client,
  method,
  url,
  data,
  requestSchema,
  responseSchema,
}: ApiRequestOptions<TResponse, TData>): Promise<TResponse> {

  let requestData = data;

  if (requestSchema) {
    try {
      requestData = requestSchema.parse(data);
    } catch (error) {
      throw new ApiRequestValidationError(url, error);
    }
  }

  const response = await client.request({
    method,
    url,
    data: requestData,
  });

  try {
    return responseSchema.parse(response.data);
  } catch (error) {
    throw new ApiResponseValidationError(url, error);
  }
}

The flow is always the same:

Validate what goes out.
Send the request.
Validate what comes back.

Making Contract Failures Explicit

Instead of throwing generic errors, validation failures get their own error types.

For example:

export class ApiResponseValidationError extends Error {
  constructor(
    public readonly url: string,
    public override readonly cause: unknown,
  ) {
    super(`API response does not match the contract for ${url}.`);
    this.name = "ApiResponseValidationError";
  }
}

Now the application can understand what happened without inspecting error messages.

A response validation failure is not the same as:

a network failure
a timeout
a server error

The failure itself carries meaning.

Validation Errors Are Not All The Same

Validation tells us that something is wrong.

But knowing that something failed is only half of the problem.

We also need to understand why it failed.

A validation problem is different from a network problem.

For example:

type ClientErrorKind =
  | "api_request_validation"
  | "api_response_validation"
  | "api_network_error"
  | "api_timeout"
  | "api_server_error";

This distinction helps debugging.

Instead of seeing:

API failed

we can understand:

Response shape changed

or:

Network request timed out

or:

Frontend sent invalid data

A consistent error model means the UI does not need to understand every possible failure source.

The API layer handles that complexity.

Error Reporting Should Also Be Safe

When adding error reporting, there is another problem:

Logs can accidentally expose sensitive information.

Errors might contain:

tokens
passwords
emails
phone numbers

So before reporting errors, sensitive values should be sanitized.

Example:

Bearer eyJhbGci...

becomes:

Bearer [REDACTED]

Observability is useful, but it should not create another security problem.

The Final Flow

The final architecture looks like this:

Conclusion

TypeScript is great at protecting our code.

But it cannot protect us from data crossing the application boundary.

APIs are runtime data, and runtime data needs runtime validation.

Adding a contract boundary between the API and the application helps us:

catch integration issues earlier
prevent invalid data from reaching application state
make errors easier to understand
build more reliable frontend systems

This approach also changed the way I think about frontend architecture:

API boundaries are not just places where data enters the application.

They are places where trust should be established.

The goal is not to eliminate every possible bug.

The goal is to make failures happen closer to their source, where they are easier to detect and fix.

Preventing Refresh Token Race Conditions in Frontend Applications

Mohamad Reza Rajabi — Sat, 29 Aug 2026 12:31:08 +0000

Race conditions are not limited to backend systems or multithreaded code.

They can also happen in frontend applications whenever multiple asynchronous operations interact with the same state or resource.

What Is a Race Condition?

A race condition happens when the result of an application depends on the timing or completion order of concurrent operations.

In frontend applications, this can happen with things like:

API requests
Promises
user interactions
timers
state updates

For example, imagine an autocomplete input:

Request A: search("r")
Request B: search("react")

If Request B finishes first but Request A finishes later, the older result may overwrite the newer one.

A useful pattern to watch for is:

Multiple async operations + shared state/resource + timing matters

One simple question can help identify these situations:

What happens if this operation starts again before the previous one finishes?

For example:

async function refreshToken() {
  // ...
}

What happens if several API requests call refreshToken() before the first refresh has completed?

That's the race condition we're going to look at next.

The Token Refresh Race Condition

Imagine the user has an expired access token and the frontend sends several API requests at almost the same time:

GET /profile
GET /orders
GET /notifications

All of them are sent with the same expired token, so the server responds with 401 Unauthorized.

A naive interceptor might handle every 401 like this:

if (error.response?.status === 401) {
  await refreshToken();
}

The problem is that each failed request runs this logic independently.

So instead of one refresh request, we may end up with:

All three requests are trying to update the same authentication state at nearly the same time.

Depending on how the backend handles refresh tokens, this can lead to unnecessary requests, inconsistent token state, or even intermittent authentication failures.

What we actually want is:

The first request should start the refresh operation, while the others wait for the same result.

This is where a shared Promise becomes useful.

Solving It with a Shared Promise

The key idea is simple:

If a refresh is already in progress, don't start another one. Wait for the existing refresh instead.

We can keep the current refresh operation in a shared Promise:

let refreshPromise: Promise<RefreshSessionData> | null = null;

function refreshSession() {
  if (!refreshPromise) {
    refreshPromise = requestNewSession().finally(() => {
      refreshPromise = null;
    });
  }

  return refreshPromise;
}

The first caller sees refreshPromise === null and starts the refresh.

While that request is still pending, every other caller receives the same Promise instead of creating another refresh request.

Once the refresh succeeds or fails, finally() resets refreshPromise back to null, so a future token expiration can start a new refresh normally.

This gives us the behavior we wanted:

One refresh operation, multiple consumers waiting for its result.

Now let's plug this into an Axios response interceptor.

Using It Inside an Axios Interceptor

Now we need to connect the shared refresh logic to our API requests.

With Axios, a response interceptor is a good place to detect 401 Unauthorized responses and recover from them.

A simplified version looks like this:

apiClient.interceptors.response.use(
  (response) => response,
  async (error) => {
    if (error.response?.status !== 401) {
      return Promise.reject(error);
    }

    const originalRequest = error.config;

    if (originalRequest._retry) {
      return Promise.reject(error);
    }

    originalRequest._retry = true;

    const session = await refreshSession();

    originalRequest.headers.Authorization =
      `Bearer ${session.accessToken}`;

    return apiClient(originalRequest);
  },
);

The flow is straightforward:

Because refreshSession() uses the shared Promise from the previous section, multiple 401 responses can reach this interceptor at the same time without starting multiple refresh calls.

The _retry flag is also important. It prevents the same request from entering an infinite 401 → refresh → retry loop if the retried request is still unauthorized.

In a production implementation, we should also avoid running this logic for the refresh endpoint itself or for endpoints that should never trigger token refresh.

At this point, concurrent 401 responses are coordinated correctly.

But there is still one subtle race condition left: what if a 401 arrives after another request has already refreshed the token?

Handling a Late `401`

There is one more edge case worth handling.

Imagine two requests are sent with the same expired token.

Request A fails first and refreshes the token successfully.

By the time Request B receives its 401, the application already has a newer access token.

If we blindly refresh on every 401, Request B would trigger another unnecessary refresh.

This can be more than just an unnecessary network call.

In systems that use refresh token rotation, the first successful refresh may invalidate the previous refresh token. A second refresh triggered by a stale 401 can then fail and, depending on the backend's session policy, may result in an unexpected session failure or even force the user to log in again.

Instead, we can compare the token used by the failed request with the token we currently have:

const failedAccessToken = getAccessTokenFromRequest(originalRequest);
const currentAccessToken = tokenStore.getAccessToken();

if (
  currentAccessToken &&
  currentAccessToken !== failedAccessToken
) {
  attachAccessToken(originalRequest, currentAccessToken);
  return apiClient(originalRequest);
}

If the tokens are different, another request has already refreshed the session.

So instead of refreshing again, we simply retry the failed request with the newer token.

This small check avoids redundant refresh calls caused by stale responses.

What If the Refresh Itself Fails?

So far, we've assumed the refresh request succeeds.

But the refresh token itself may also be expired, revoked, or invalid.

Because all concurrent requests are waiting for the same refreshPromise, they will all receive the same rejection if the refresh fails.

However, there is an important detail:

Session-level side effects should happen inside the shared refresh operation — not inside every waiting request.

For example:

async function requestNewSession() {
  try {
    const response = await publicClient.post("/auth/refresh");

    tokenStore.setAccessToken(response.data.accessToken);

    return response.data;
  } catch (error) {
    if (isUnauthorizedApiError(error)) {
      tokenStore.clearAccessToken();
      tokenStore.notifyUnauthorized();
    }

    throw error;
  }
}

This is important because not every refresh failure necessarily means the session is invalid.

A temporary network failure or server error may be recoverable, while an unauthorized refresh response usually means the session can no longer be restored.

By keeping these session-level side effects inside the shared refresh operation, an unrecoverable authentication failure clears the session once, while every request waiting for that Promise receives the same rejection.

The refresh operation is shared, so its session-level failure handling should be shared too.

Testing the Race Condition

Race conditions are timing-dependent, so we should not rely on network timing and simply hope that concurrent requests overlap during the test.

For these tests, I used Vitest together with custom Axios adapters, which lets the test control the request lifecycle without making real network calls.

The important part is controlling exactly when the refresh request is allowed to finish.

For that, I use a small deferred() helper:

function deferred<T>() {
  let resolve!: (value: T | PromiseLike<T>) => void;
  let reject!: (reason?: unknown) => void;

  const promise = new Promise<T>((res, rej) => {
    resolve = res;
    reject = rej;
  });

  return { promise, resolve, reject };
}

This gives the test manual control over a Promise.

Now we can intentionally keep the refresh request pending:

const refreshGate = deferred<void>();
let refreshCalls = 0;

const { apiClient } = setupClients(async (config) => {
  refreshCalls += 1;

  await refreshGate.promise;

  return successfulRefresh(config);
});

Then we fire several requests at almost the same time:

const requests = [
  apiClient.get("/resource/1"),
  apiClient.get("/resource/2"),
  apiClient.get("/resource/3"),
];

Because the refresh request is still blocked, all three requests can enter the 401 recovery flow while the same refresh operation is still pending.

At that point, we verify that only one refresh has started:

await vi.waitFor(() => {
  expect(refreshCalls).toBe(1);
});

Then we allow the refresh to complete:

refreshGate.resolve();

Finally, we verify that all original requests recover successfully and that the refresh endpoint was still called only once:

await expect(
  Promise.all(requests),
).resolves.toHaveLength(3);

expect(refreshCalls).toBe(1);

The failure path should be tested too.

For the failure case, we configure the refresh request to reject and verify that every request waiting for the shared Promise fails while only one refresh attempt is made.

const refreshError = new Error("Session expired");
let refreshCalls = 0;

const { apiClient } = setupClients(async () => {
  refreshCalls += 1;
  throw refreshError;
});

const results = await Promise.allSettled([
  apiClient.get("/resource/1"),
  apiClient.get("/resource/2"),
]);

expect(results).toEqual([
  expect.objectContaining({ status: "rejected" }),
  expect.objectContaining({ status: "rejected" }),
]);

expect(refreshCalls).toBe(1);

The important idea is that we are not only testing the final result.

We are deliberately controlling the timing of asynchronous operations to reproduce the concurrency scenario we want to protect against.

The late-401 case can be tested the same way by delaying one API response until another request has already completed the token refresh.

Conclusion

Race conditions in frontend applications are often hidden behind asynchronous behavior.

A useful question to keep in mind is:

What happens if this operation starts again before the previous one finishes?

In our token-refresh flow, multiple 401 responses were competing to refresh the same authentication state.

A shared Promise allowed those requests to coordinate around a single refresh operation, while comparing the failed token with the current token handled late 401 responses without triggering unnecessary refreshes.

We also made sure that refresh failures are handled inside the shared operation itself, so session-level side effects such as clearing authentication state happen only once while every waiting request receives the same failure.

The important part is not just the token-refresh implementation.

It is learning to recognize when multiple asynchronous operations are competing over the same resource because that is where race conditions often begin.

DEV Community: Mohamad Reza Rajabi

From Contract Boundary to Error Boundary: Structuring API Error Handling in a TypeScript Frontend

Quick Recap: The Validation Boundary

The Core Idea: One Error Shape, One Boundary

Step 1: Normalizing Everything at the Axios Interceptor

Step 2: Error Responses Are External Data Too, Validate Them

Step 3: Keeping Technical Detail Away From Users

Step 4: Mapping Backend Validation Errors Into Forms

Step 5: Sanitizing Before You Log Anything

Putting It All Together: A Signup Form

Why This Is Worth the Extra Code

TypeScript Types Are Not Enough: Building a Runtime API Contract Boundary

The TypeScript Safety Illusion

A Real Failure Scenario

API Responses Are Untrusted Data

The Simple Approach

Creating an API Contract Boundary

Keeping Contracts In A Shared Validation Layer

What The Boundary Actually Looks Like

Making Contract Failures Explicit

Validation Errors Are Not All The Same

Error Reporting Should Also Be Safe

The Final Flow

Conclusion

Preventing Refresh Token Race Conditions in Frontend Applications

What Is a Race Condition?

The Token Refresh Race Condition

Solving It with a Shared Promise

Using It Inside an Axios Interceptor

Handling a Late 401

What If the Refresh Itself Fails?

Testing the Race Condition

Conclusion

Handling a Late `401`