Errors and troubleshooting
Every KashRock status code, what it means, and what your app or agent should do about it.
| Status | You see | It means | Do this |
|---|---|---|---|
| 401 | error.code = "invalid_key" | The key is missing, wrong, or turned off. | Send it as the x-api-key header (Authorization: Bearer also works). Copy it again from the console. |
| 403 | error.code = "plan_required" | This endpoint is not in your plan. required_plan names the plan that has it. | Do not retry. Tell the user which plan unlocks it; upgrade.url opens checkout with that plan picked. |
| 402 | limit_type = "daily", "monthly" or "live_lines" | Your credits for the day or month are spent. | Wait for resets_at, add a credit pack (credits_url), or move up a plan. Retrying will not help. |
| 429 | limit_type = "rpm", "concurrency" or "heavy_capacity" | Too many requests at once. You still have credits. | Wait the Retry-After seconds, then retry. Cache slow-changing data and poll live data no faster than you need. |
| 200, empty | An empty matches, live or plays list | Nothing matches right now: no live match, or a quiet market. | Show an empty state. It is a real answer, not an error, and no plan changes it. |
| 200, no stats | has_live_stats = false with a reason | The match is live but no live source is covering it right now. | Show the match without stats. Upgrading does not add coverage for a match. |
| 200, delayed | A data_delay block on live data | Your plan reads live data with a delay (15 seconds on Hobby). | Expected on Hobby. Builder and up are real time. |
The plan gate
A 403 names the plan that has the endpoint and a checkout link for it:
{
"error": {
"code": "plan_required",
"message": "consensus lines and live odds is not in your plan. Your current plan is: sandbox.",
"status": 403,
"required_plan": "hobby",
"upgrade": { "message": "...", "url": "https://www.kashrock.com/checkout/start?...&plan=hobby", "plan": "hobby" }
}
}Show upgrade.message and upgrade.url to the user. Do not retry.
Rate and credit limits
429 means too fast: wait Retry-After seconds. 402 means the day's or month's credits are spent: wait for resets_at, add a credit pack, or move up a plan. Details on Plans, credits and limits.
Empty and partial answers
- An empty list (no live matches, a quiet market) is a real answer. Show an empty state.
has_live_stats: falsewith areasonmeans no live source covers that match right now. No plan changes that.available: falsewith areasonandhintmeans the data is not ready yet; the hint names the next step.- A query parameter an endpoint does not read is refused with
400 invalid_param, naming the parameter to use instead.
Agents can turn any of these into plain English with the explain_error MCP tool.
