Skip to content
Wicket

Errors and JSON-RPC codes

Wicket returns standard HTTP status codes for REST API calls and JSON-RPC error objects for MCP proxy calls. MCP errors carry both an HTTP status and a JSON-RPC error object — well-behaved MCP clients read the JSON-RPC object.

MCP proxy errors (/mcp)

A failed MCP call returns a JSON-RPC error object:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Authorization denied: tool 'delete_file' is not permitted for agent 'my-first-agent'"
  }
}

By HTTP status

HTTP statusWhen
400Malformed JSON body, missing/invalid jsonrpc or method field, or a tools/call name without the service__ prefix
401Missing Bearer token, or unknown/invalid member key
403Agent is disabled, or your membership is not approved
405GET request to /mcp — MCP message exchange is POST-only
412Tool call was authorized, but you have no credentials connected for that service
429Rate limit exceeded for your member key
502Upstream MCP server unreachable, or internal proxy error
504Upstream MCP server did not respond within the timeout (30 s)
200 + error objectPolicy denial, service not enabled for the agent, or unsupported method

JSON-RPC error codes

CodeMeaning
-32700Parse error — request body is not valid JSON
-32600Invalid request, authentication failure, or authorization denied (policy or service allowlist)
-32601Unknown method, unknown service prefix, or unsupported operation
-32602Invalid params — e.g. tools/call without a service__tool prefixed name
-32603Upstream error, upstream timeout, missing service credentials, or internal proxy error
-32001GitHub App installation not registered — re-provision required

Common error messages

MessageWhat to do
Missing Bearer token — add your member key to the MCP client configAdd Authorization: Bearer <member-key> to your client config
Unknown member key — re-authenticate at the UI to get a new keyYour key was rotated or revoked — generate a new one from the Members tab
Agent is disabled — contact the agent ownerThe owner toggled the agent off
Membership not approved — contact the agent ownerYour join request is still pending or was rejected
Authorization denied: tool '<tool>' is not permitted for agent '<name>'A policy denied the call — check the Audit tab for the matched policy
Authorization denied: service '<service>' is not enabled for agent '<name>'The owner has not enabled this connector on the agent
Tool name must be prefixed with service name, e.g. 'github__get_file_contents'Use the prefixed tool name from tools/list
No <service> credentials configured. Connect your <service> account in the UI.Complete the connector OAuth flow from the Members tab
Rate limit exceeded — too many requests per keySlow down; see Rate limits

Policy deny messages

When a forbid policy has a deny message set (up to 500 characters), Wicket records it in the audit entry for the denied call. Open the Audit tab and expand the entry to see the message alongside the matched policy. Use deny messages to tell members why a call was blocked — “Destructive GitHub operations are blocked outside business hours” beats a bare deny.

HTTP errors (REST API)

The dashboard REST API (/api/*) uses standard status codes:

StatusMeaningCommon cause
400 Bad RequestMalformed request or failed validationMissing required field, invalid value, or invalid policy configuration (e.g. deny message over 500 characters)
401 UnauthorizedNot authenticatedNo session — sign in again
403 ForbiddenAuthenticated but not allowedCaller is not the agent owner, or member not approved
404 Not FoundResource does not existWrong agent ID, deleted policy, or member not found
409 ConflictState conflictA policy with that name already exists (create or rename)
429 Too Many RequestsRate limit exceededToo many sign-in codes requested (15 per email per hour)
500 Internal Server ErrorUnexpected server errorRetry; contact support if it persists