# Errors > Independent. Not affiliated with, endorsed by or sponsored by Novig. Canonical: https://novigapi.com/docs/endpoints/errors Facts checked: 2026-11-12 novigapi.com errors return a JSON body with a code and message: 400 bad parameter, 401 bad key, 403 plan feature, 404 unknown id, 429 rate or monthly limit with plan, reset time and upgrade link, and 503 with Retry-After. Errors cost no credits. Novig's own API also answers 429 with Retry-After, checked 12 Nov 2026. (Source: [Novig docs: Throttling](https://docs.novig.com/api/throttling.md)) ## What it returns Every error has the same envelope: an `error` object with a machine `code` and a human `message`, plus fields for the case. No error is billed. There is no 402: running out of credits is a 429 with `code: QUOTA_EXCEEDED`, and nothing is charged automatically. Status codes | Status | code | Cause | What to do | | --- | --- | --- | --- | | 400 | INVALID_QUERY | A parameter has the wrong form | Read `message`; it names the parameter. | | 400 | MISSING_PARAMETER | A required parameter is missing, such as `market_id` on fair-price | Read `message`; it names what to send. | | 400 | INVALID_LIMIT | `limit` is not a whole number in the endpoint's range | Send a smaller `limit`. | | 400 | INVALID_CURSOR | `cursor` is not one we issued | Send `meta.next_cursor` from the previous page unchanged. | | 401 | INVALID_API_KEY | Missing, malformed or revoked key | Send `Authorization: Bearer nv_...` with an active key. | | 403 | UPGRADE_REQUIRED | The feature is not on your plan, such as bulk CSV, webhooks or history older than the Free window | The body names the plan that has it and an `upgrade_url`. | | 403 | ACCOUNT_SUSPENDED | The account is suspended | Contact support; retrying will not help. | | 404 | NOT_FOUND | Unknown or closed market id | Check the id; closed markets move to [results](https://novigapi.com/docs/endpoints/results). | | 429 | RATE_LIMITED | Over your per-minute ceiling | Wait for `Retry-After` (30 s). | | 429 | QUOTA_EXCEEDED | Monthly credits used up, or this call needs more than are left | Upgrade, or add 1,000 credits for $9, one time; or wait for `reset_at`. | | 503 | SERVICE_UNAVAILABLE | Temporary problem on our side or at the source | Retry after `Retry-After` (5 s); quote `X-Request-ID` to support. | Webhook management adds `INVALID_JSON` (400), `INVALID_URL` and `INVALID_WEBHOOK` (422) and `WEBHOOK_LIMIT` (409). The stream refuses an upgrade with `STREAM_CONNECTION_LIMIT` (429) when every connection your plan allows is open. ## Parameters This endpoint takes no parameters. ## Request ```bash curl -s -i "https://novigapi.com/api/v1/markets?league=NBA" \ -H "Authorization: Bearer nv_..." # HTTP/2 429 # content-type: application/json ``` ## Response The 429 a Free account gets after its monthly credits run out, trimmed: the full body also carries `upgrade_options`, `value`, `projected_monthly_credits`, `usage` (with `top_paths`) and a `topup` object. Links in a Free account's body are signed so they open checkout without a sign-in; the ones shown are simplified. ```json { "error": { "plan": "free", "limit": 100, "reset_at": "2026-12-01T00:00:00.000Z", "agent_next_step": "Tell your user their app is stopped until the reset or an upgrade. Include user_message in that message word for word: it has the one-click upgrade link.", "notify_user": true, "user_message": "Your app is stopped: your Novig API Free plan used all 100 of its credits for this month, so it gets no new data until 1 Dec (UTC). To keep going now, Developer is $49 a month for 10,000 credits: https://novigapi.com/upgrade?plan=developer&source=rest (opening the link charges nothing). Or add 1,000 credits for $9, one time: https://novigapi.com/topup?source=rest", "retryable": false, "remaining": 0, "required": 1, "upgrade_url": "https://novigapi.com/upgrade?plan=developer&source=rest", "recommended_plan": "developer", "topup_url": "https://novigapi.com/topup?source=rest", "code": "QUOTA_EXCEEDED", "message": "Free includes 100 requests a month. Upgrade at https://novigapi.com/pricing." } } ``` ## Fields Response fields | Field | Type | Description | | --- | --- | --- | | error.code | string | Machine-readable code from the table above. | | error.message | string | Human-readable explanation. | | error.plan | string | 429 only: your plan id. | | error.limit | integer | 429 only: the limit you hit, per minute or per month. | | error.reset_at | string (ISO 8601) | 429 only: when the limit resets (next minute, or 00:00 UTC on the 1st). | | error.upgrade_url | string | 429 only: the one-click upgrade to the recommended plan. | | error.agent_next_step, notify_user, user_message | string, boolean, string | 429 only: what an agent should do, whether to tell its user, and the exact sentence to pass on. | | error.retryable, retry_after_seconds | boolean, integer | False on the monthly limit; true with 30 seconds on the per-minute limit. | | error.topup_url | string | Monthly 429 only: one-click link to buy 1,000 credits for $9. | ## Credit cost Errors cost 0 credits, including 400, 401, 403, 404, 429 and 5xx. ## Python ```python import os import requests KEY = os.environ["NOVIGAPI_API_KEY"] # nv_... HEADERS = {"Authorization": f"Bearer {KEY}"} import time def get(path, params=None, tries=4): for attempt in range(tries): r = requests.get("https://novigapi.com/api/v1" + path, params=params, headers=HEADERS, timeout=10) if r.status_code == 429 and r.json()["error"]["code"] == "RATE_LIMITED": time.sleep(int(r.headers.get("Retry-After", "30"))) continue if r.status_code >= 500: time.sleep(int(r.headers.get("Retry-After", "5")) * (attempt + 1)) continue if r.status_code == 429: # QUOTA_EXCEEDED: do not retry, tell the user raise RuntimeError(r.json()["error"].get("user_message") or r.json()["error"]["message"]) r.raise_for_status() return r.json() raise RuntimeError("gave up after retries") ``` ## JavaScript ```javascript const KEY = process.env.NOVIGAPI_API_KEY; // nv_... const headers = { Authorization: "Bearer " + KEY }; async function get(path, tries = 4) { for (let attempt = 0; attempt < tries; attempt++) { const res = await fetch("https://novigapi.com/api/v1" + path, { headers }); if (res.ok) return res.json(); const body = await res.json().catch(() => ({})); const code = body.error?.code; const wait = Number(res.headers.get("retry-after") ?? 5) * 1000; if (code === "RATE_LIMITED" || res.status >= 500) { await new Promise((r) => setTimeout(r, wait)); continue; } throw new Error(body.error?.user_message ?? body.error?.message ?? "HTTP " + res.status); } throw new Error("gave up after retries"); } ``` ## Notes and edge cases - Do not retry 400, 401, 403, 404 or QUOTA_EXCEEDED; they will fail the same way. - Over MCP, the same bodies arrive as tool results with `isError: true`. - A 304 Not Modified (when you send `If-None-Match`) is not an error and costs 0. - If a 503 persists, our collector may have paused reads from Novig on purpose; the [status of the source](https://novigapi.com/novig-api) is shown on the site. ## Sources - [Novig docs: Throttling](https://docs.novig.com/api/throttling.md) - [Novig docs: Errors](https://docs.novig.com/api/errors.md) - [Novig API docs](https://docs.novig.com) --- Get a free API key: https://novigapi.com/sign-up . Docs: https://novigapi.com/docs . MCP: https://novigapi.com/api/mcp . Operated by Stunning Couches LLC. Independent. Not affiliated with, endorsed by or sponsored by Novig.