An Error Occurred While Contacting the API: Finding the Real Failure

This message almost always comes from a catch block that swallowed the actual error and printed something friendly instead. The real failure is a status code, a timeout, a DNS error, or a CORS rejection, and none of that is in the sentence you are looking at. The first job is not fixing anything, it is recovering what was thrown away.

Search this phrase and you will find it in tutorials, sample projects, and shipped applications, all using the same shape of code. Understanding that shape is what turns this from a mystery into a two-minute diagnosis.

Table of contents

• Where the message comes from
• Reproduce it outside your application
• The six causes, and how each announces itself
• When the caller is a browser
• Making the next occurrence cheaper
• How this fits the rest of the stack
• FAQ

Where the message comes from

It is generated by code that looks like this, in one language or another.

try:
    response = requests.post(url, json=payload)
    result = response.json()
except Exception as e:
    print("An error occurred while contacting the API.")   # e is discarded

The exception carried everything useful: the status code, the response body, the connection error. The handler replaced it with a fixed string and moved on.

So the first fix is to the error handling, not to the API call, and it takes one line.

import logging

try:
    response = requests.post(url, json=payload, timeout=30)
    response.raise_for_status()
    result = response.json()
except requests.HTTPError as e:
    logging.error(
        "API returned %s: %s",
        e.response.status_code,
        e.response.text[:500],
    )
    raise
except requests.RequestException as e:
    logging.error("API request failed: %r", e)
    raise

Two things to note. raise_for_status turns a 4xx or 5xx into an exception, which the original code did not do, so a failed request was being parsed as JSON and failing confusingly at that step instead. And logging the response body is what tells you which of the causes below applies, because APIs put the reason there.

Keep the user-facing message friendly. Just do not make it the only record that anything happened.

Reproduce it outside your application

Once you have the status code, confirm it with curl. This separates a problem with the API from a problem with your code, which is the most valuable split you can make early.

curl -v -X POST https://api.example.com/v1/things \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"test"}' \
  -w '\nstatus=%{http_code} dns=%{time_namelookup}s connect=%{time_connect}s total=%{time_total}s\n'

The timing output localises a slow failure precisely. A large namelookup time is DNS. A large connect time with a small namelookup is network or TLS. A large total with both small is the API itself being slow.

If curl succeeds and your application fails, the difference is in your code: a header not being sent, a different base URL between environments, a proxy configured in the runtime, or a payload that is not what you think it is.

Log the outgoing request in that case, with the token redacted. A surprising proportion of these turn out to be a request that does not look like what the developer believes it looks like.

The six causes, and how each announces itself

Grouped by what the recovered error will tell you.

• 401 or 403: authentication. An expired token, a key that is not set in this environment, a scope that was never granted, or a token for the wrong environment entirely.
• 404: the URL is wrong. Usually a missing version prefix, a trailing slash the API cares about, or a base URL pointing at the wrong environment.
• 422 or 400: the payload is malformed. The body of the response will name the field, which is why logging it matters so much.
• 429: rate limited. Read the Retry-After header and back off rather than retrying immediately.
• 5xx: the API is broken, not you. Retry with backoff and check their status page before spending time on your own code.
• No status at all: the request never completed. DNS failure, connection refused, TLS handshake failure, or a timeout.

That last category is the one where people waste the most time, because there is no response to inspect. The distinguishing questions: does the hostname resolve, does the port accept a connection, and does the TLS handshake complete.

dig +short api.example.com
nc -zv api.example.com 443
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>&1 | head -20

TLS failures deserve a specific mention because they produce confusing errors. An expired certificate on the API’s side, a missing intermediate certificate that browsers tolerate and libraries do not, or an outdated CA bundle in an old container image all produce a verification failure that reads like a network problem.

When the caller is a browser

If this happens in front-end JavaScript, there is an additional cause that does not exist server-side, and it is by far the most common one: CORS.

The distinguishing symptom is that the browser console shows a CORS message while the network tab shows the request completing, sometimes with a 200. The server answered; the browser refused to hand the response to your code because the required headers were absent.

The fetch error itself is deliberately vague, which is why the message ends up generic. The real detail is in the console, not in the caught exception.

// The status here is 0 and the message is generic on a CORS failure.
// The actual reason is printed to the console by the browser.
try {
  const res = await fetch(url, { method: "POST", body });
  if (!res.ok) {
    const text = await res.text();
    throw new Error(`API ${res.status}: ${text.slice(0, 300)}`);
  }
  return await res.json();
} catch (err) {
  console.error("Request failed:", err);   // check the console, not just this
  throw err;
}

CORS is enforced by the browser and configured on the server, so it cannot be fixed in your front-end code. The options are to configure the API to send the right headers if you control it, or to call it from your own backend if you do not.

That second option is usually correct anyway. Calling a third-party API directly from the browser means the API key is in the client, where anyone can read it. Proxying through your own service keeps the credential server-side and removes the CORS problem at the same time.

Making the next occurrence cheaper

1. Never discard an exception. Log the status, the response body, and the request identifier if the API returns one, then show the user whatever you like.
2. Set explicit timeouts on every outbound call. Many clients default to no timeout, so a hung request holds a connection indefinitely.
3. Retry only what is retryable: 5xx, 429, and connection failures, with exponential backoff. Never retry a 400 or a 401, which will fail identically forever.
4. Include a correlation identifier in your requests and log it, so a support conversation with the API provider can reference specific calls.
5. Fail loudly in development and gracefully in production, rather than the same way in both.
6. Check the provider’s status page before debugging your own code when the failure is a 5xx and started suddenly.

The first item removes most of the cost of this entire category. The reason a generic message is expensive is not the message, it is that the information needed to act on it existed for a moment and was thrown away.

How this fits the rest of the stack

Recovering these errors depends on logs existing somewhere you can reach, tied to the deploy that produced them, which is exactly what is missing when the only record is a console line on a server nobody can access. Services on RunxBuild keep runtime logs alongside the build log for each deploy, so the failing request and the release that introduced it are in the same place. The RunxBuild hosting calculator shows the service and its managed database as separate line items.

Useful related references:

• Looping in Bash: for, while, until, and the Loop That Eats Your Filenames
• NFS Access Denied by Server: 6 Causes and the Right Fixes
• 400 error code in rest api: The Nine Reasons and the Three That Hide Behind “Bad Request”
• Services on RunxBuild

FAQ

What does an error occurred while contacting the API mean?

It is a generic message from a catch block that discarded the real error. The underlying failure is a status code, a timeout, a DNS or TLS problem, or a CORS rejection. Log the exception properly to find out which.

How do I find the real API error?

Log the status code and the response body from the exception, then reproduce with curl -v. The timing breakdown from curl separates DNS, connection, and server-side slowness, and the response body usually names the actual problem.

Why does my API call work in curl but not in my application?

The requests differ. Common causes are a header not being sent, a different base URL between environments, a proxy configured in the runtime, or a payload that is not shaped as intended. Log the outgoing request with credentials redacted.

Is a CORS error the same as an API error?

No. The server answered successfully and the browser refused to expose the response because the required headers were missing. It is enforced client-side and configured server-side, so it cannot be fixed in front-end code.

Which API errors should I retry?

5xx responses, 429 rate limits honouring Retry-After, and connection-level failures, all with exponential backoff. Never retry 400, 401, or 404, which will fail the same way every time.