# Rate limits and errors

> Errors are JSON with an `error` message, and upgrade or reset hints where relevant.

## Error codes

| Status | Error | What to do |
|---|---|---|
| 401 | API key required | No key sent. Pass X-API-Key or ?api_key=. Get a free key instantly at https://koboterminal.com/api#get-key |
| 401 | Invalid API key | The key does not exist. Check for typos or copy it again from your email. |
| 403 | API key is not active / has expired | The key was revoked, expired, or a paid period ended. Renew at https://koboterminal.com/api |
| 403 | Plan upgrade required | The endpoint needs a higher plan. The body includes current_plan, required plan and upgrade_url. |
| 429 | Daily limit exceeded | You used today's allowance. Resets at midnight WAT (reset_at in the body). The body names the next plan. |
| 400 | Bad request | A parameter is malformed, e.g. a date not in YYYY-MM-DD. |
| 404 | Not found | Unknown symbol, index or ETF. |
| 5xx | Upstream or server error | Retry with backoff. Data is cached, so retries are cheap. |

### Example: daily limit reached

```json
{
  "error": "Daily limit exceeded",
  "limit": 100,
  "message": "You've used all 100 requests on the Free plan today...",
  "current_plan": "Free",
  "upgrade_url": "https://koboterminal.com/api",
  "next_plan": "starter",
  "reset_at": "2026-11-18T23:00:00.000Z"
}
```

## Rate limits

| Plan | Price (NGN) | Price (USD) | Requests / day | Requests / min | Best for |
|---|---|---|---|---|---|
| **Free** | Free | Free | 100 | 10 | Learning, prototypes, personal dashboards |
| **Starter** | ₦29,000/mo | $20/mo | 1,000 | 20 | Solo builders and small apps |
| **Professional** | ₦75,000/mo | $50/mo | 10,000 | 60 | Production apps, fintechs, client work |
| **Institutional** | ₦350,000/mo | $200/mo | 50,000 | 120 | Brokers, asset managers, trading terminals |

## Good practice

- **Cache.** Prices refresh every 20 minutes during market hours (10:00 to 14:30 WAT). Polling more often than that returns the same numbers.
- **Check the clock.** Call `/api/ngxdata/market-status` and stop polling when `is_open` is false.
- **Use the bulk endpoint.** One `/api/ngxdata/stocks` call returns every stock: cheaper than 150 single-stock calls.
- **Read `stale_after`.** Market payloads tell you when to refresh.
- **Back off on 5xx.** Retry after 2, 4, 8 seconds.
