Error Reference

This page covers every error code you can receive - both from the platform itself and from your handler’s runtime.

---

HTTP errors

These are returned by Rival’s runtime before or after your code runs.

Code	Name	When it happens	What to do
400	Bad Request	Malformed request body - missing event field or invalid JSON	Verify your request payload is valid JSON and contains an event field
401	Unauthorized	Missing or invalid API key in the Authorization header	Pass your key as Authorization: <key> (no Bearer prefix)
402	Payment Required	Run Balance is empty - execution blocked before running	Top Up your Run Balance or upgrade your plan
404	Not Found	Tool or version does not exist	Check the tool ID and version on the tool’s detail page
408	Timeout	Your handler exceeded its configured timeout limit (max 300s)	Reduce work per call or split into smaller invocations
500	Internal Server Error	Unhandled exception thrown by your handler	Inspect the run in Executions and fix the handler logic

---

Runtime errors (500)

When your handler throws an uncaught exception, the platform returns an HTTP 200 with a statusCode: 500 in the body:

{
  "statusCode": 500,
  "body": "{\"error\": \"Runtime error: <message>\"}"
}

The body field is always a JSON string - parse it to read the error message.

Python

{
  "statusCode": 500,
  "body": "{\"error\": \"Runtime error: division by zero\"}"
}

JavaScript

{
  "statusCode": 500,
  "body": "{\"error\": \"Script execution failed\", \"type\": \"ReferenceError\", \"details\": \"foo is not defined\"}"
}

Lua

{
  "statusCode": 500,
  "body": "{\"error\": \"Script execution failed\", \"type\": \"RuntimeError\", \"details\": \"attempt to index a nil value\"}"
}

---

Returning errors intentionally

Your handler can return any statusCode to signal errors to callers:

def cortexone_handler(event, context):
    if not event.get("id"):
        return {"statusCode": 400, "body": {"error": "id is required"}}
    return {"statusCode": 200, "body": {"ok": True}}

This is the recommended pattern for validation errors - use HTTP semantics to signal the problem.

---

MCP error codes (JSON-RPC)

MCP tools return JSON-RPC 2.0 errors inside the response body. These are not HTTP errors - the HTTP status is always 200.

Code	Name	When to use
-32700	Parse error	Request was not valid JSON
-32600	Invalid request	jsonrpc field missing or not "2.0"
-32601	Method not found	Your handler does not implement the requested method
-32602	Invalid params	Arguments are missing or wrong type
-32603	Internal error	Unexpected error inside your handler logic

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found: prompts/list"
  }
}

---

Common mistakes

Symptom	Likely cause	Fix
401 on every request	API key missing or wrong header format	Pass key as Authorization: <key> - no Bearer prefix
402 on every request	Run Balance is empty	Top Up from the Run Balance card in Billing
404 on valid tool ID	Wrong version string	Check the version on your tool’s detail page
500 with null body	Handler returned None/undefined/nil	Always return {statusCode, body}
Body is a JSON string, not object	Expected behavior	Parse response.body in your application

---