Skip to main content

​
Common Issues & Solutions

​
Authentication Errors

​
”Invalid or missing authentication” (401)

Problem: Your API key or JWT token is invalid or missing. Solutions:
  • Verify your API key is correct and hasn’t been regenerated
  • Check that you’re including the Authorization: Bearer header
  • For JWT tokens, ensure they haven’t expired
  • Make sure you’re using the correct header format
# Correct format
Authorization: Bearer your_api_key_here
x-alloy-userid: your_user_id_here

# Common mistakes
Authorization: your_api_key_here  # Missing "Bearer" prefix
x-user-id: ...  # Wrong header name (should be x-alloy-userid)

​
”Rate limit exceeded” (429)

Problem: You’ve exceeded 100 requests per minute. Solutions:
  • Implement exponential backoff in your retry logic
  • Batch operations where possible
  • Consider caching frequently accessed data
  • For high-volume use cases, contact support for rate limit increases

​
MCP Protocol Issues

​
”Credential not found” error

Problem: The connector requires authentication but no credential exists. Solutions:
  1. First create a credential using the create_credential_alloy tool
  2. List existing credentials with get_credentials_alloy
  3. Pass the credential ID in your action execution
{
  "name": "execute_action_alloy",
  "arguments": {
    "connectorId": "slack",
    "actionId": "chat_postMessage",
    "credentialId": "cred_abc123",  // Include credential ID
    "parameters": { ... }
  }
}

​
”Action not found” error

Problem: The action ID doesn’t exist for this connector. Solutions:
  • Use get_connector_resources_alloy to list available actions
  • Check for typos in the action ID (case-sensitive)
  • Verify the connector supports the action you’re trying to use

​
Server Configuration Issues

​
Server not accepting requests

Problem: Getting 403 Forbidden errors. Check these restrictions:
  1. User restrictions: Is your user ID allowed?
  2. Connector restrictions: Is the connector in your allowlist?
  3. Action restrictions: Is the specific action blocked?
  4. Public/Private mode: Are you using the correct authentication?
// Example: Check your server's restrictions
GET /api/servers/{serverId}

// Response will show active restrictions
{
  "restrictions": {
    "connectors": {
      "mode": "allowlist",
      "allowedIds": ["slack", "notion"]  // Only these are allowed
    }
  }
}

​
Token URL not working

Problem: Self-sufficient token URL returns 401. Possible causes:
  • Token has expired (check tokenExpiresInDays setting)
  • Server was deleted
  • Token was regenerated
Solution: Get a fresh token URL by fetching server details again.

​
OAuth & Credential Issues

​
OAuth redirect not working

Problem: OAuth flow fails or redirects to wrong URL. Solution: Include the x-redirect-uri header: 
POST /mcp/{serverId}/{token}
x-redirect-uri: https://your-app.com/oauth/callback
Content-Type: application/json

​
API Key credentials not working

Problem: Non-OAuth credentials fail to authenticate. Common issues:
  1. Wrong field names: Each connector expects specific field names
  2. Missing required fields: Some connectors need multiple fields
// Example: Creating ShipStation credentials
{
  "name": "create_credential_alloy",
  "arguments": {
    "connectorId": "shipStation-oas",
    "authenticationType": "apiKey",
    "fields": {
      "api-key": "your_key",     // Exact field name required
      "api-secret": "your_secret" // Both fields needed
    }
  }
}
Use get_credential_metadata_alloy to see exact requirements.

​
Data & Response Issues

​
”needsRefinement” response

Problem: Getting guidance instead of data. This happens when:
  • Result set is too large (>50 items)
  • Platform API would be overwhelmed
  • More specific parameters are needed
Solution: Add filtering parameters: 
{
  "parameters": {
    "limit": 10,        // Limit results
    "query": "search",  // Add search terms
    "status": "active"  // Filter by status
  }
}

​
Truncated responses

Problem: Response data is cut off. By design: Responses are limited to prevent overwhelming the AI.
  • Arrays: Maximum 25 items shown
  • Strings: Maximum 5KB per field
  • Use pagination for more data

​
Debugging Tips

​
1. Enable verbose logging

Check response headers and error details for more context.

​
2. Test incrementally

  1. First test authentication with a simple tools/list call
  2. Then try listing connectors
  3. Finally attempt your actual operation

​
3. Validate your request format

{
  "jsonrpc": "2.0",          // Required
  "method": "tools/call",     // Exact method name
  "params": {                 // Parameters object
    "name": "tool_name",
    "arguments": { ... }
  },
  "id": "unique_id"          // Request ID
}

​
Getting Help

​
Check the documentation

Authentication Guide

API Reference

Available Tools

​
Contact support

​
Common error codes reference

CodeMeaningAction Required
INVALID_REQUESTMalformed requestCheck JSON syntax
UNAUTHORIZEDAuth failedVerify credentials
FORBIDDENAccess deniedCheck restrictions
NOT_FOUNDResource missingVerify IDs exist
RATE_LIMITEDToo many requestsImplement backoff
CREDENTIAL_NOT_FOUNDNo auth for connectorCreate credential
CONNECTOR_NOT_FOUNDInvalid connectorCheck connector ID
ACTION_NOT_FOUNDInvalid actionVerify action exists
⌘I