Error Codes

RouterMCP uses standard JSON-RPC 2.0 error codes plus custom codes for specific scenarios.

JSON-RPC 2.0 Standard Errors

Code	Message	Description
`-32700`	Parse error	Invalid JSON was received
`-32600`	Invalid request	Missing required fields
`-32601`	Method not found	Unknown method
`-32602`	Invalid params	Invalid method parameters
`-32603`	Internal error	Server error

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid request"
  }
}

Custom Error Codes

Code	Message	Description
`-32000`	Project not found	Invalid project slug
`-32001`	Unauthorized	Missing or invalid API key
`-32002`	Tool not found	Unknown tool name
`-32003`	Tool disabled	Tool exists but is disabled
`-32004`	Upstream error	Error from upstream MCP server
`-32005`	Rate limit exceeded	Too many requests

HTTP Status Codes

Status	Description
`200 OK`	Success
`201 Created`	Resource created
`400 Bad Request`	Invalid request body or parameters
`401 Unauthorized`	Missing or invalid authentication
`403 Forbidden`	Insufficient permissions
`404 Not Found`	Resource not found
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Server error
`502 Bad Gateway`	Upstream server error
`503 Service Unavailable`	Temporary outage

Error Response Format

MCP Protocol Errors

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Unauthorized",
    "data": {
      "reason": "Invalid API key"
    }
  }
}

Rate Limit Errors

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please try again later.",
  "retryAfter": 30
}

Handling Errors

JavaScript

async function callMcp(projectSlug, apiKey, method, params) {
  const response = await fetch(
    `https://gateway.routermcp.com/v1/mcp/${projectSlug}/request`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: Date.now(),
        method,
        params
      })
    }
  );
  
  if (!response.ok) {
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      throw new Error(`Rate limited. Retry after ${retryAfter}s`);
    }
    throw new Error(`HTTP ${response.status}`);
  }
  
  const data = await response.json();
  
  if (data.error) {
    switch (data.error.code) {
      case -32001:
        throw new Error('Invalid API key');
      case -32002:
        throw new Error(`Tool not found: ${params?.name}`);
      case -32004:
        throw new Error(`Upstream error: ${data.error.message}`);
      default:
        throw new Error(data.error.message);
    }
  }
  
  return data.result;
}

Python

import requests

class McpError(Exception):
    def __init__(self, code, message):
        self.code = code
        super().__init__(message)

def call_mcp(project_slug, api_key, method, params=None):
    response = requests.post(
        f'https://gateway.routermcp.com/v1/mcp/{project_slug}/request',
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {api_key}'
        },
        json={
            'jsonrpc': '2.0',
            'id': 1,
            'method': method,
            'params': params or {}
        }
    )
    
    if response.status_code == 429:
        retry_after = response.headers.get('Retry-After', 30)
        raise McpError(-32005, f'Rate limited. Retry after {retry_after}s')
    
    response.raise_for_status()
    data = response.json()
    
    if 'error' in data:
        raise McpError(data['error']['code'], data['error']['message'])
    
    return data['result']

Common Issues

401 Unauthorized

Check that your API key is correct and the project's authMode is set to api_key.

404 Not Found on /v1/mcp/...

Ensure you're using /v1/mcp/ (not /1/mcp/) and the path ends with /request for the JSON-RPC endpoint.

-32002 Tool not found

Tool names must include the server alias prefix, e.g., github.create_issue not just create_issue.

Error Codes and HTTP Status Reference