Errors: HTTP Codes and Streamed JSON Payloads

Lexera returns conventional HTTP codes on the transport layer and streams descriptive JSON error payloads over SSE for tool execution failures.

Lexera uses conventional HTTP status codes for transport-level issues and streams detailed JSON error payloads over the open SSE connection when a tool execution fails. Understanding the difference helps you distinguish between a connection problem and a business-logic rejection, so you can respond with the correct fix.

Error signatures

Error signature	Description	Resolution
Insufficient AED wallet balance	The workspace wallet lacks the required AED to authorize the jurisdiction pricing tier for lexera_route_to_specialist.	Ask a workspace finance administrator to top up the wallet balance.
Invalid inputs (Zod Error)	The JSON-RPC arguments failed schema validation, for example a missing required parameter or a type mismatch.	Review the path and expected fields in the error payload to correct the argument names.
HTTP 401 Unauthorized	The request used an invalid, missing, or expired API key.	Ensure the Bearer token is correctly formatted in the Authorization header.

Streamed error payload example

When a tool execution fails, the error is delivered as a JSON-RPC response over SSE with isError: true:

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"Insufficient AED wallet balance. This review requires AED 699.00; ask your finance administrator to add a corporate wallet credit.\"}"
      }
    ],
    "isError": true
  },
  "jsonrpc": "2.0",
  "id": 1
}

Detailed error reference

Insufficient AED wallet balance

This error occurs when lexera_route_to_specialist attempts to place a temporary hold on the corporate AED wallet and the balance is below the required tier. The streamed payload includes the exact amount needed (for example, AED 699.00 for UAE).

Resolution: Contact a workspace finance administrator to add a corporate wallet credit, then retry the dispatch.

Invalid inputs (Zod Error)

This error occurs when the JSON-RPC params.arguments object does not match the tool’s schema. Common causes include missing required fields (such as document_text or target_jurisdiction), incorrect types, or typos in argument names.

Resolution: Inspect the path and expected fields in the error payload to identify which argument is invalid, then correct the payload and retry.

HTTP 401 Unauthorized

This error occurs on the transport layer when the Authorization header is missing, malformed, or contains an expired or revoked API key. All authenticated MCP tools require a valid Bearer token.

Resolution: Verify that the header is exactly Authorization: Bearer lex_... and that the key is active in the Lexera Developer Dashboard. Regenerate the key if necessary.