How to Fix 401 Unauthorized Error When Calling the API

When working with APIs, running into an HTTP 401 Unauthorized error can be frustrating. It usually means that the request wasn’t authenticated properly — most often because of an issue with your API key.

If you’re using the Geoapify APIs, a 401 error is one of the most common issues new users face. The good news is that it’s quick to fix once you know what to check.

In this short FAQ, we’ll explain what a 401 error means, list the most common causes, and walk you through how to resolve it so you can get your project running smoothly again.

What does “401 Unauthorized” mean?

The 401 Unauthorized status code tells you that the request could not be completed because the server did not receive valid authentication credentials or API key. In other words, the API expected an API key (or another form of authentication), but it was missing, invalid, or rejected.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid apiKey"
}

It’s important to note that 401 is different from 403:

• 401 Unauthorized → you are not authenticated (the server doesn’t recognize your credentials).
• 403 Forbidden → you are authenticated but not allowed to access that resource.

Other common 4xx codes

The 401 Unauthorized error is just one of several client-side HTTP status codes (4xx family). You can find the full list in the Wikipedia page on HTTP status codes.

Here are a few you might encounter most often when working with APIs:

Status Code	Meaning	Typical Cause
400 Bad Request	The server could not understand the request.	Missing or invalid parameters, malformed URL.
401 Unauthorized	Authentication is missing or invalid.	No API key, wrong key, or not sent correctly.
403 Forbidden	You are authenticated but not allowed to access the resource.	Key doesn’t have permission, IP/domain restrictions, or access denied.
404 Not Found	The requested resource doesn’t exist.	Wrong endpoint, typo in URL, or resource removed.
429 Too Many Requests	You have exceeded the allowed request limit.	Hitting rate limits or quota exhaustion.

Understanding these codes helps quickly identify whether the issue is with authentication (401), permissions (403), request formatting (400), missing resources (404), or usage limits (429).

Why 401 stands out

Unlike the other 4xx errors, 401 specifically indicates an authentication problem or problem with API key. It doesn’t mean your request is malformed (400), the resource is missing (404), or you’ve gone over quota (429). It means the API simply doesn’t recognize who you are — usually because the API key is missing, wrong, or invalid.

Common reasons for 401 errors

Here are the most common reasons you might see a 401 Unauthorized when calling an API:

Reason	Description
Missing API key	The request does not include the required apiKey parameter. Example: https://api.geoapify.com/v1/geocode/search?text=Berlin
Typo in API key	The key is mistyped, cut off, or contains hidden characters (like spaces or line breaks from copy-paste). Example: apiKey=12345OOPS instead of apiKey=12345OPS
Not URL-encoded	The key or query parameters are not properly URL-encoded, so special characters break the request. Example: When sending an address to Geocoding API it must be URL encoded. In other words, it should be29%20Buxton%20Road%2C%20London%2C%20E15%201QU%2C%20United%20Kingdom instead of just 29 Buxton Road, London, E15 1QU, United Kingdom
Key in the wrong place	The API key is sent in the wrong part of the request (e.g., header instead of query parameter). See API authentication basics. Example: sending Authorization: apiKey instead of ?apiKey=...
Inactive key	The key is expired, deleted, or disabled. Learn more about API key lifecycle. Example: using an old key after rotation
Restricted key	The key has domain, IP, or referrer restrictions that block the request. Example: request from localhost when the key only allows example.com
Environment variable issue	The app doesn’t load the key correctly, often leaving the value empty. Example: request with apiKey= and no value

How to fix a 401 error

Here’s a simple step-by-step approach:

1. Test with curl Run the request directly with curl to see if it works outside your code:

   curl "https://api.geoapify.com/v1/geocode/search?text=29%20Buxton%20Road%2C%20London%2C%20E15%201QU%2C%20United%20Kingdom&format=json&apiKey=YOUR_API_KEY"

• If it works here, the issue is in your code.
• If it fails, the problem is with your API key or request setup.

1. If the issue is in your code
   Debug and check what request your code actually sends. Compare it with the working curl request to spot the difference.

2. If the issue is with your API key

• Try again with a newly created API key.
• Check for domain, IP, or referrer restrictions that may block your request.
• If nothing helps, contact Support and share your request details. Geoapify users can email [e-mail].

Summary

A 401 Unauthorized error means your request didn’t pass authentication — most often because the API key is missing, wrong, or restricted.

To solve it, first test the request with curl to see if the problem comes from your code or the API key.

• If it’s your code, debug the request it generates.
• If it’s the key, try a new one, check restrictions, and if needed, reach out to [e-mail] for support.

You can also use the Geoapify API Playground to test requests interactively, generate ready-to-use links, and copy working examples. This is the easiest way to verify your API key and request format.

With these steps, you can quickly identify the root cause and get your API calls working again.