Common API Errors and How to Fix Them

Every REST API communicates failure through HTTP status codes, but the same code can mean different things depending on the API and the situation. Knowing what each status code actually implies — and what to check first — saves hours of guesswork. This guide covers the six error codes developers run into most often when integrating with third-party or internal APIs, along with concrete fixes for each one.

400 Bad Request

A 400 means the server understood who you are and where you're sending the request, but the request body or parameters are malformed or invalid. This is almost always a client-side problem — missing a required field, sending a string where a number is expected, or malformed JSON.

{
  "error": "Bad Request",
  "message": "\"email\" is required and must be a valid email address"
}

Fix: read the error message body carefully — good APIs tell you exactly which field failed validation. Validate your payload against the API's documented schema before sending it.

401 Unauthorized vs 403 Forbidden

These two are mixed up constantly. A 401 means the request has no valid credentials at all — your API key or bearer token is missing, malformed, or expired. A 403 means you ARE authenticated, but your account or token simply doesn't have permission for that specific action or resource.

• 401: check that the Authorization header is present and formatted as the API expects, e.g. Bearer <token>
• 401: check whether your token has expired and needs a refresh
• 403: check the account's role or scope — you may need to request elevated API permissions

404 Not Found

A 404 means the URL path itself doesn't map to any resource on the server. In practice this is usually a typo in the endpoint path, a missing ID in the URL, using the wrong API version prefix (like /v1/ vs /v2/), or querying an ID that was deleted.

// Broken: missing the resource id
fetch('https://api.example.com/v1/users/');

// Fixed
fetch('https://api.example.com/v1/users/482');

429 Too Many Requests

APIs rate-limit clients to protect their infrastructure. A 429 means you crossed that limit. Most APIs include a Retry-After header telling you how many seconds to wait.

async function callWithBackoff(url, options, retries = 3) {
  const res = await fetch(url, options);
  if (res.status === 429 && retries > 0) {
    const wait = Number(res.headers.get('Retry-After') || 2) * 1000;
    await new Promise((r) => setTimeout(r, wait));
    return callWithBackoff(url, options, retries - 1);
  }
  return res;
}

1. Read and respect the Retry-After header instead of retrying instantly
2. Batch multiple operations into fewer requests where the API supports it
3. Cache responses you don't need to re-fetch on every call
4. Ask the provider for a higher rate limit if your usage genuinely needs it

500 Internal Server Error

Unlike the 4xx codes above, a 500 means the failure is on the server side, not something wrong with your request. If it's your own API, check the server logs — the client response body rarely has enough detail to diagnose it. If it's a third-party API, the safest move is to retry with backoff and check the provider's status page before assuming your code is at fault.

Frequently Asked Questions