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 the execution gateway before or after your code runs.

Code	Name	Cause
400	Bad Request	Malformed request body — missing event field or invalid JSON
401	Unauthorized	Missing or invalid API key in the Authorization header
402	Payment Required	Insufficient wallet balance — execution blocked before running
404	Not Found	Function ID or version does not exist
408	Timeout	Your handler exceeded its configured timeout limit
500	Internal Server Error	Unhandled exception thrown by your handler

Caution

A 402 means execution was blocked before your code ran — you are not charged. Top up your balance in Settings → Billing.

Note

A 408 timeout is not charged. Reduce execution time or increase the timeout limit in your version settings.

---

Runtime errors (500)

When your handler throws an uncaught exception, the platform returns 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"
  }
}

Tip

Return a JSON-RPC error object (not an HTTP error) for unknown methods or bad params in MCP tools. See the MCP guide for the full handler pattern.

---

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	Wallet balance is zero	Top up from Settings → Billing
404 on valid function 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