> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ngnmarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> All NGN Market API error codes & their HTTP status, and how to fix them.
When a request fails, the response sets `success` to `false` and returns an `error` object with a machine-readable `code` and a human-readable `message`. All error responses follow the same envelope described in [Response format](/response-format).
## Error code reference
| Error code | Status | Meaning |
| :---------------- | :----: | :--------------------------------------------- |
| `MISSING_API_KEY` | 401 | `Authorization` header is missing or malformed |
| `INVALID_API_KEY` | 401 | API key not found or has been revoked |
| `PLAN_REQUIRED` | 403 | Endpoint requires a higher-tier plan |
| `IP_NOT_ALLOWED` | 403 | Request IP is not in this key's allowlist |
| `RATE_LIMITED` | 429 | Per-minute request limit exceeded |
| `QUOTA_EXCEEDED` | 429 | Monthly call limit reached |
| `NOT_FOUND` | 404 | Route or resource does not exist |
| `SERVER_ERROR` | 500 | Unexpected error on the server |
## Troubleshooting
**What it means:** Your request did not include an `Authorization` header, so the API cannot identify your account.
**How to fix it:** Add your API key to every request using the `Authorization` header with the `Bearer` scheme:
```bash theme={null}
curl https://api.ngnmarket.com/v1/market/snapshot \
-H "Authorization: Bearer ngm_live_YOUR_KEY"
```
All endpoints except `/health` require authentication. If you are using an HTTP client or library, check that it is not stripping the `Authorization` header on redirects. Some clients drop headers by default when following a 301 or 302 response.
**What it means:** The key in your `Authorization` header was not recognised. This happens when the key does not exist, has been deleted, or has been revoked.
**How to fix it:**
1. Open your [developer dashboard](https://ngnmarket.com/developer) and confirm the key is still active.
2. Copy the key value directly from the dashboard to rule out a typo or truncation.
3. Check that you are using the full key, including the `ngm_live_` prefix.
4. If you recently rotated or deleted a key, update all integrations that used the old one.
If your key appears valid in the dashboard but still returns this error, contact [support](https://ngnmarket.com/contact).
**What it means:** The endpoint you called requires a higher plan than your current one. The error response includes `required_plan` and `current_plan` so you know exactly what is needed:
```json theme={null}
{
"success": false,
"error": {
"code": "PLAN_REQUIRED",
"message": "This endpoint requires a starter plan or higher.",
"required_plan": "starter",
"current_plan": "free"
}
}
```
**How to fix it:**
* Check the [Plans](/plans) page to see which endpoints each tier unlocks.
* Upgrade to at least the plan named in `required_plan` from your [developer dashboard](https://ngnmarket.com/developer).
* If you think you are already on the required plan, confirm your plan tier in the dashboard.
**What it means:** Your API key has an IP allowlist configured and the request came from an IP address not on that list. This is an opt-in security feature. Keys with no allowlist entries accept requests from any IP.
```json theme={null}
{
"success": false,
"error": {
"code": "IP_NOT_ALLOWED",
"message": "This API key is restricted to specific IP addresses. Check your allowlist in the developer dashboard."
}
}
```
**How to fix it:**
1. Open your [developer dashboard](https://ngnmarket.com/developer) and navigate to the key that returned this error.
2. Check the IP allowlist configured for that key.
3. Add your current IP address (or CIDR range) to the allowlist, or remove the allowlist entries entirely to allow all IPs.
4. If you are behind a load balancer or proxy, the IP seen by the API may differ from your machine's IP. Check the `X-Forwarded-For` header your proxy sends.
**What it means:** Your account has exceeded the per-minute request limit for your plan. This is distinct from `QUOTA_EXCEEDED`, which applies to the monthly call quota. Per-minute limits reset automatically after 60 seconds.
```json theme={null}
{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Please slow down and try again."
}
}
```
**How to fix it:**
* Wait 60 seconds and retry the request.
* Reduce the rate at which your application sends requests to stay within your plan's per-minute cap. See [Rate Limits](/rate-limits) for the limits per plan.
* If you consistently hit this limit, consider upgrading to a higher plan.
**What it means:** Your account has used all of its monthly API calls. No further requests will succeed until your quota resets or you upgrade. This error includes a `meta` object so you can confirm the reset date:
```json theme={null}
{
"success": false,
"error": {
"code": "QUOTA_EXCEEDED",
"message": "Monthly call limit of 100,000 reached. Resets on 2026-05-01T00:00:00.000Z."
},
"meta": {
"plan": "starter",
"calls_used": 100000,
"calls_remaining": 0,
"reset_at": "2026-05-01T00:00:00.000Z"
}
}
```
**How to fix it:**
* **Wait for the reset.** Your quota resets on the 1st of the next month at midnight UTC. The exact time is in `meta.reset_at`.
* **Upgrade your plan.** Log in to your [developer dashboard](https://ngnmarket.com/developer) and select a higher plan. Upgrades take effect immediately. See [Plans](/plans) for limits and pricing.
To avoid this in future, monitor `meta.calls_remaining` and reduce usage or upgrade before you hit zero.
**What it means:** The URL path you requested does not match any route on the API.
**How to fix it:**
1. Check the [API Reference](/api-reference/introduction) to confirm the correct path and HTTP method.
2. Make sure any path parameters like `:symbol` are substituted correctly, for example `/companies/DANGCEM` not `/companies/:symbol`.
3. Confirm you are using the correct base URL: `https://api.ngnmarket.com/v1`.
4. Check for trailing slashes or typos. Paths are case-sensitive.
**What it means:** An unexpected error occurred on the NGN Market servers. This is not caused by your request and does not count against your quota.
**How to fix it:**
1. Retry the request after a short delay. Most server errors are transient.
2. If the error persists for several minutes, check the [NGN Market status page](https://ngnmarket.com/status) for any active incidents.
3. If you can reliably reproduce the error, report it to [support](https://ngnmarket.com/contact) with the endpoint, request details, and approximate time of the failure.
## Frequently asked questions
It depends on the error. Requests that fail authentication (`MISSING_API_KEY` or `INVALID_API_KEY`) and requests blocked by rate limits (`RATE_LIMITED` or `QUOTA_EXCEEDED`) do not count against your monthly quota. Requests that pass authentication and quota checks but return `PLAN_REQUIRED`, `NOT_FOUND`, or `SERVER_ERROR` are counted because they were already validated.
The API does not send proactive notifications, but you can build your own alerting by reading `meta.calls_remaining` in every response. When it falls below a threshold you define, trigger an alert in your application or monitoring system.
Confirm the header is formatted exactly as `Authorization: Bearer ngm_live_YOUR_KEY` with a single space after `Bearer`. Some HTTP clients modify or strip headers. Log the outgoing request headers to verify they are sent correctly, and check that no whitespace or newline characters were introduced when copying the key.