# Error Codes and Common Fixes

Common API error codes with causes and fixes, ordered by how frequently we observe the resolutions.

## 4010 - Invalid Key[​](#4010 "Direct link to 4010 - Invalid Key")

**Message:** `Invalid Key` **HTTP Status:** 401

Your API Key was not recognised. The key may be incorrect or malformed.

### Potential Fixes[​](#potential-fixes "Direct link to Potential Fixes")

1. **Check for typos** — copy the key directly from your dashboard.
2. **Check querystring parameter name** — ensure the key is passed as `api_key` and not `api-key`.
3. **Check Authorization header format** — ensure the header is formatted as `IDEALPOSTCODES api_key="ak_yourkey"`.

## 4011 - URL Not on Allowed List[​](#4011 "Direct link to 4011 - URL Not on Allowed List")

**Message:** `Requesting URL not on whitelist` **HTTP Status:** 401

The request's `Referer` or `Origin` header did not match any URL on your key's [allowed URL list](/docs/guides/allowed-urls.md).

### Potential Fixes[​](#potential-fixes-1 "Direct link to Potential Fixes")

1. **Check if you need Allowed URLs** — non-browser requests won't contain the `Referer` or `Origin` headers needed for matching. Remove Allowed URLs if the key is kept private.
2. **Review your Allowed URL configuration** — check the [API Key security guide](/docs/guides/api-key-secure.md) to ensure URLs have been defined correctly.

## 4020 - Balance Depleted[​](#4020 "Direct link to 4020 - Balance Depleted")

**Message:** `Key balance depleted` **HTTP Status:** 402

Your API Key has no remaining lookup balance.

### Potential Fixes[​](#potential-fixes-2 "Direct link to Potential Fixes")

1. **Top up your balance** — purchase more lookups from your dashboard.
2. **Enable automated top-ups** — prevent this from recurring by [enabling automated top-ups](/docs/guides/automated-topups.md).

## 4021 - Lookup Limit Reached[​](#4021 "Direct link to 4021 - Lookup Limit Reached")

**Message:** `Lookup Limit Reached` **HTTP Status:** 402

Your API Key has a daily or IP rate limit configured, and it has been reached.

### Potential Fixes[​](#potential-fixes-3 "Direct link to Potential Fixes")

1. **Disable the rate limit** — remove the responsible limit in your key settings for an immediate fix.
2. **Increase the limit** — adjust the daily or IP limit in your key settings.