Errors

Every failed REST call answers with an HTTP error status and one JSON object, error. The codes are the same for every tool.

Over MCP, a tool that fails returns the same code, message and issues in its result, marked isError. A request the MCP server refuses before any tool runs gets a JSON-RPC error instead. See The MCP server.

The error envelopeCopy Anchor Link

Write your code against code, not the wording of message, and show message to the person using your app.

Every codeCopy Anchor Link

ExamplesCopy Anchor Link

A bad argument: calc_implied_probability with odds of 50, which American odds cannot be.

{
  "error": {
    "code": "invalid_input",
    "message": "americanOdds: American odds must be +100 or more, or -100 or less.",
    "issues": [
      {
        "path": "americanOdds",
        "message": "American odds must be +100 or more, or -100 or less."
      }
    ]
  }
}

A tool that saves to your account, called with a read-only token:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="unitley", error="insufficient_scope", scope="write"
Content-Type: application/json

{
  "error": {
    "code": "insufficient_scope",
    "message": "log_bet saves to your account, and this access token is read-only. Create a token with write access on the Connect page to use it.",
    "issues": []
  }
}

Authentication challengesCopy Anchor Link

A token problem comes with a WWW-Authenticate header that says what is wrong:

The MCP server answers a refused token differently. Both 401s carry Bearer error="invalid_token", error_description="…" with the message, and the body is {"error":"invalid_token","error_description":"…"} rather than the envelope. A read-only token calling a tool that saves gets no challenge there: the tool's result is the insufficient_scope error. See The MCP server.

The messages say what to do:

• No token: "Send a Unitley access token as Authorization: Bearer unt_... (create one on the Connect page)."
• A dead token: "This access token is unknown, revoked or expired. Create a new one on the Connect page."
• The wrong scope: the tool's name, then "saves to your account, and this access token is read-only. Create a token with write access on the Connect page to use it."

Create tokens on the Connect page. See Tokens and security.

Retry-AfterCopy Anchor Link

Every 429 rate_limited answer has a Retry-After header, in seconds, and the same number in retryAfterSeconds. The message ends with the wait in words, such as "Try again in a minute."

• "Too many requests." means the per-address budget is spent.
• "Too many tool calls." means your per-token or per-user budget is spent.
• "jev_classify is limited to" means that tool's own budget is spent.
• "Jev is busy." means TypeSafe asked Unitley to wait.

Budgets count in fixed windows that reset on the clock. A call made before the wait is over is refused again and still counts, and it does not bring the reset any closer. See Rate limits.

Retry or fixCopy Anchor Link

Some errors go away if you wait. The rest come back until you change the request.

Fix the request firstCopy Anchor Link

Wait and retryCopy Anchor Link