Enhancement: axiosInstance: no error handling/interceptors & env validation #7

New Issue

2026-06-17T14:11:08Z

abumahid commented

2026-06-17 14:11:08 +00:00

axiosInstance: no error handling/interceptors & env validation

Description

The current Axios instance is minimally configured with a baseURL sourced from import.meta.env.VITE_API_URL and a fixed timeout value.

The implementation lacks:

Runtime validation of VITE_API_URL
Request interceptors
Response interceptors
Global error normalization
Authentication token handling strategy
Retry/backoff handling for transient failures

This creates inconsistent API behavior across the application and increases the likelihood of hard-to-debug networking issues.

Impact

Application may fail unexpectedly when VITE_API_URL is missing or misconfigured.
API errors are handled inconsistently across different features.
Poor developer experience when debugging network issues.
Increased risk of duplicate error-handling logic throughout the codebase.
Future authentication implementations may introduce security issues if token attachment is implemented inconsistently.
Temporary network failures are not retried.

Location

src/api/axiosInstance.ts

Approximate Lines

~3–9

Suggested Fix

1. Validate Environment Configuration

Verify that VITE_API_URL exists during application startup.

Fail fast with a clear and actionable error message if the variable is missing.

Example

const apiUrl = import.meta.env.VITE_API_URL;

if (!apiUrl) {
  throw new Error(
    "Missing VITE_API_URL environment variable"
  );
}

2. Add Request Interceptor

Introduce a centralized request interceptor for:

Authentication headers
Request tracing
Correlation IDs
Future request-level configuration

Example responsibilities:

Attach access token
Add custom headers
Log requests in development mode

3. Add Response Interceptor

Normalize API errors into a consistent format.

Handle common cases:

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
429 Rate Limited
500+ Server Errors
Network Errors
Timeout Errors

Example:

axiosInstance.interceptors.response.use(
  response => response,
  error => {
    return Promise.reject(
      normalizeApiError(error)
    );
  }
);

4. Retry Transient Failures

Consider automatic retries for:

Network interruptions
Connection resets
Temporary server failures
429 responses (when appropriate)

Recommended approaches:

Exponential backoff
Retry limits
Retry only idempotent requests

5. Define Authentication Strategy

If authentication is planned:

Centralize token attachment logic.
Avoid duplicating authorization header code.
Document storage strategy.
Ensure logout/token refresh behavior is handled consistently.

Acceptance Criteria

Validate VITE_API_URL during application startup.
Application fails with a clear error when configuration is invalid.
Request interceptor is implemented (or architecture documented if deferred).
Response interceptor normalizes API errors.
Common API error cases are handled consistently.
Retry strategy is implemented or documented.
Authentication attachment strategy is documented or implemented.
Existing functionality remains unchanged.
No new TypeScript or ESLint errors are introduced.

Local Verification

Run the following commands before creating the PR.

Build

npm run build

Lint Check

npm run lint

Manual Testing

Environment Validation

Start application with valid VITE_API_URL.
Confirm application functions normally.
Remove VITE_API_URL.
Confirm startup fails with a helpful error message.

Error Handling

Simulate network failure.
Simulate API timeout.
Simulate 401 response.
Simulate 403 response.
Simulate 500 response.
Verify normalized error behavior.

Authentication (If Implemented)

Verify auth header is attached correctly.
Verify unauthenticated requests behave correctly.
Verify logout behavior remains functional.

# axiosInstance: no error handling/interceptors & env validation ## Description The current Axios instance is minimally configured with a `baseURL` sourced from `import.meta.env.VITE_API_URL` and a fixed timeout value. The implementation lacks: * Runtime validation of `VITE_API_URL` * Request interceptors * Response interceptors * Global error normalization * Authentication token handling strategy * Retry/backoff handling for transient failures This creates inconsistent API behavior across the application and increases the likelihood of hard-to-debug networking issues. ## Impact * Application may fail unexpectedly when `VITE_API_URL` is missing or misconfigured. * API errors are handled inconsistently across different features. * Poor developer experience when debugging network issues. * Increased risk of duplicate error-handling logic throughout the codebase. * Future authentication implementations may introduce security issues if token attachment is implemented inconsistently. * Temporary network failures are not retried. ## Location `src/api/axiosInstance.ts` ### Approximate Lines ~3–9 --- ## Suggested Fix ### 1. Validate Environment Configuration Verify that `VITE_API_URL` exists during application startup. Fail fast with a clear and actionable error message if the variable is missing. ### Example ```ts id="xygmje" const apiUrl = import.meta.env.VITE_API_URL; if (!apiUrl) { throw new Error( "Missing VITE_API_URL environment variable" ); } ``` --- ### 2. Add Request Interceptor Introduce a centralized request interceptor for: * Authentication headers * Request tracing * Correlation IDs * Future request-level configuration Example responsibilities: * Attach access token * Add custom headers * Log requests in development mode --- ### 3. Add Response Interceptor Normalize API errors into a consistent format. Handle common cases: * 400 Bad Request * 401 Unauthorized * 403 Forbidden * 404 Not Found * 429 Rate Limited * 500+ Server Errors * Network Errors * Timeout Errors Example: ```ts id="7nn7q0" axiosInstance.interceptors.response.use( response => response, error => { return Promise.reject( normalizeApiError(error) ); } ); ``` --- ### 4. Retry Transient Failures Consider automatic retries for: * Network interruptions * Connection resets * Temporary server failures * 429 responses (when appropriate) Recommended approaches: * Exponential backoff * Retry limits * Retry only idempotent requests --- ### 5. Define Authentication Strategy If authentication is planned: * Centralize token attachment logic. * Avoid duplicating authorization header code. * Document storage strategy. * Ensure logout/token refresh behavior is handled consistently. --- ## Acceptance Criteria * [ ] Validate `VITE_API_URL` during application startup. * [ ] Application fails with a clear error when configuration is invalid. * [ ] Request interceptor is implemented (or architecture documented if deferred). * [ ] Response interceptor normalizes API errors. * [ ] Common API error cases are handled consistently. * [ ] Retry strategy is implemented or documented. * [ ] Authentication attachment strategy is documented or implemented. * [ ] Existing functionality remains unchanged. * [ ] No new TypeScript or ESLint errors are introduced. --- ## Local Verification Run the following commands before creating the PR. ### Build ```bash id="nkp4b8" npm run build ``` ### Lint Check ```bash id="s2qf4h" npm run lint ``` --- ## Manual Testing ### Environment Validation * [ ] Start application with valid `VITE_API_URL`. * [ ] Confirm application functions normally. * [ ] Remove `VITE_API_URL`. * [ ] Confirm startup fails with a helpful error message. ### Error Handling * [ ] Simulate network failure. * [ ] Simulate API timeout. * [ ] Simulate 401 response. * [ ] Simulate 403 response. * [ ] Simulate 500 response. * [ ] Verify normalized error behavior. ### Authentication (If Implemented) * [ ] Verify auth header is attached correctly. * [ ] Verify unauthenticated requests behave correctly. * [ ] Verify logout behavior remains functional.

abumahid added the Kind/Enhancement label 2026-06-17 14:11:08 +00:00

abumahid added this to the techzaa-frontend project 2026-06-17 14:11:08 +00:00

rimi referenced this issue

2026-06-17 16:13:32 +00:00

Fix/api/fixed api error handling #14

rimi moved this to Done in techzaa-frontend on 2026-06-17 16:23:54 +00:00

rimi closed this issue

2026-06-17 16:24:25 +00:00

Sign in to join this conversation.