JavaScript API Integration Guide: Fetch, Authentication, Errors, Retries, and Testing

Overview

A useful API integration has four responsibilities: build a correct request, protect credentials, interpret the response, and recover safely when something goes wrong. Keeping these responsibilities visible makes debugging easier than scattering request logic across individual components.

Start with a small request helper

The Fetch API resolves its promise when the server returns an HTTP response, including many error statuses. It does not automatically reject for a 400 or 500 response, so check response.ok or inspect response.status explicitly.

async function requestJson(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      Accept: "application/json",
      ...options.headers
    }
  });

  const contentType = response.headers.get("content-type") || "";
  const body = contentType.includes("application/json")
    ? await response.json()
    : await response.text();

  if (!response.ok) {
    const error = new Error(`API request failed: ${response.status}`);
    error.status = response.status;
    error.body = body;
    throw error;
  }

  return body;
}

This helper is deliberately limited. It does not assume every endpoint uses the same authentication method, response shape, or retry policy. Those decisions belong at the integration boundary, where they can be tested and documented.

Choose authentication for the execution environment

For a server-side JavaScript application, an API key or bearer token should normally be loaded from environment variables or a secret-management system rather than committed to source control. The related guide on environment variables in JavaScript apps covers local setup and the difference between server-only and client-exposed values.

Do not place a private API key in browser JavaScript simply because the request is convenient there. Anything shipped to a browser can be inspected by the user. Browser applications commonly use a public identifier, a short-lived access token, or a server endpoint that keeps the private credential out of the client. OAuth integrations also require careful handling of redirect URLs, state, token expiry, and storage.

When debugging a token-based integration, decode a JWT only to inspect its structure and claims; decoding does not prove that a token is authentic or currently valid. Use the JWT validation guide for the distinction between reading and verifying tokens.

Validate data at the boundary

TypeScript types and JSDoc improve development feedback, but they do not validate data received over the network at runtime. Check required fields, expected primitive types, nullable values, and pagination properties before passing a response deeper into the application. A small schema-validation layer can turn an unexpected upstream change into a clear integration error instead of a confusing rendering failure.

Maintenance cycle

API integrations should have an owner and a review interval. A lightweight maintenance cycle is more effective than waiting for production failures.

At initial implementation

• Record the API base URL, endpoint paths, HTTP methods, required headers, authentication method, and expected response examples.
• Document whether the endpoint is safe to retry and whether requests are idempotent.
• Define timeouts, pagination behavior, acceptable status codes, and the treatment of empty responses.
• Keep secrets outside the repository and add a test configuration that uses mocks or a sandbox.
• Capture a correlation or request identifier when the API provides one, while avoiding sensitive values in logs.

During routine review

Review the integration on a schedule that matches its importance. A frequently used payment, identity, or data-synchronization path deserves more attention than an occasional internal utility. Confirm that the documentation still matches the code, credentials can be rotated, tests cover the current response shape, and monitoring distinguishes authentication failures from temporary network problems.

Review dependency and runtime changes as part of the same process. If the project changes its Node.js version, browser support, TypeScript configuration, or HTTP client, rerun the integration tests rather than assuming request behavior is unchanged. The Node version manager comparison and TypeScript configuration guide can help standardize those development environments.

Keep examples executable

An API example becomes stale when it contains an old endpoint, obsolete field name, or authentication assumption. Prefer small examples that can run against a mock server or recorded fixture. Store representative success, validation-error, unauthorized, rate-limit, and server-error responses with tests. When a response changes, update the fixture, parser, and documentation together.

Signals that require updates

Some changes should trigger an immediate review rather than waiting for the regular cycle.

• Authentication changes: A new token format, scope requirement, consent flow, or expiration behavior can invalidate both request code and deployment configuration.
• Endpoint or schema changes: Renamed fields, altered nesting, new required parameters, and changed pagination tokens require contract tests and parser updates.
• New error behavior: If an API introduces different status codes or structured error bodies, update the error mapper and user-facing messages.
• Rate-limit notices: New quotas, headers, or retry guidance may require changes to backoff, concurrency, and queueing logic.
• Operational symptoms: Spikes in timeouts, 401 responses, 403 responses, malformed payloads, or duplicate writes are evidence that the integration needs investigation.
• Search-intent changes: When developers increasingly ask about a new authentication flow, runtime, framework, or API pattern, revise the tutorial so its examples remain relevant without replacing the underlying principles.

Do not treat every failure as a reason to retry. A 400 response generally indicates a request that must be corrected, while a 401 may require reauthentication and a 429 or transient 5xx response may be recoverable. The exact classification depends on the API contract, so encode it deliberately rather than guessing from a generic status list.

Common issues

Missing or misleading error handling

Wrapping every failure in a message such as “request failed” loses useful information. Preserve the status, a safe version of the response body, and the operation name. At the same time, do not log access tokens, passwords, full authorization headers, or personal data. Separate developer diagnostics from messages shown to end users.

Retries that create duplicate work

Retries are appropriate only when the operation and API contract allow them. Use a bounded number of attempts, increasing delays, and a little random variation to avoid many clients retrying simultaneously. A timeout does not prove that the server did not process a write, so retrying a non-idempotent operation can create duplicates. Where supported, use an idempotency key or reconcile the result before repeating the request.

async function withRetry(operation, attempts = 3) {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    try {
      return await operation();
    } catch (error) {
      const retryable = error.status === 429 || error.status >= 500;
      if (!retryable || attempt === attempts - 1) throw error;
      const delay = 300 * 2 ** attempt + Math.random() * 150;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

This example is a starting point, not a complete policy. Add a request timeout with AbortController, respect a server-provided retry delay when appropriate, and avoid retrying requests that the user has cancelled.

CORS confused with authentication

A browser may block a cross-origin request because of CORS even when the endpoint and credentials are correct. CORS is enforced by the browser and must be configured by the server; adding an arbitrary browser header or disabling security checks is not a production fix. Use the CORS error guide to separate preflight, origin, credential, and server-response problems.

Pagination and rate limits ignored

Never assume the first response contains every record. APIs may return a page number, cursor, continuation URL, or total indicator. Follow the documented mechanism and stop when the server indicates there is no next page. For large collections, prefer incremental processing over loading everything into memory. Rate limits also affect concurrency: a pool of controlled workers is safer than launching hundreds of requests with Promise.all().

Tests that cover only success

Mock the network boundary and test the cases that change application behavior: malformed JSON, an empty result, expired authentication, forbidden access, a rate limit, a timeout, and a valid response with optional fields missing. Add one integration test against a controlled environment when possible, but keep most tests deterministic and fast.

When to revisit

Use a scheduled review cycle for important integrations and revisit immediately after an API provider announces a breaking change, authentication update, deprecation, quota adjustment, or response-schema revision. Also review after upgrading the JavaScript runtime, changing deployment infrastructure, exposing a new browser client, or observing a failure pattern that the current tests do not explain.

A practical review checklist is:

1. Run unit and integration tests against representative success and failure fixtures.
2. Confirm environment variables and secret rotation procedures without printing secret values.
3. Compare request and response contracts with the provider’s current documentation.
4. Verify timeout, cancellation, retry, pagination, and rate-limit behavior.
5. Inspect logs for actionable error context and accidental sensitive data.
6. Update the request helper, examples, tests, and documentation in the same change.

Finally, record the review date, integration owner, contract version or documentation reference, and any known limitations. That small maintenance record gives the next developer a clear starting point and keeps a JavaScript API integration guide useful long after its original implementation.