Skip to Content
KashRock Docs

Errors and troubleshooting

Every KashRock status code, what it means, and what your app or agent should do about it.

StatusYou seeIt meansDo this
401error.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.
403error.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.
402limit_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.
429limit_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, emptyAn empty matches, live or plays listNothing 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 statshas_live_stats = false with a reasonThe 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, delayedA data_delay block on live dataYour 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: false with a reason means no live source covers that match right now. No plan changes that.
  • available: false with a reason and hint means 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.

On this page