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-statusand stop polling whenis_openis false. - Use the bulk endpoint. One
/api/ngxdata/stockscall 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.