Troubleshooting

Common issues and their solutions when working with the Agent API.

Error Catalog

Error	HTTP Code	Cause	Fix
Unauthorized	401	Invalid or expired token	Re-authenticate. Tokens expire after 24 hours.
Forbidden	403	Invalid API key	Verify x-api-key header value
Bad Request	400	Invalid GraphQL syntax	Check query/mutation syntax and variable types
Too Many Requests	429	Credit or QPS limit exceeded	Wait 60 seconds, then retry
NO_DOCS	In error field	No documents matched the query	Broaden search terms or adjust time range
TIMEOUT	In error field	Search took too long	Retry with a simpler query or use fast mode

Authentication Issues

• Token expired -- Re-call the /auth endpoint. Tokens last 24 hours (expires_in: 86400).
• Wrong credentials -- Verify your email, password, client_id, client_secret, and api_key are all correct.
• Missing headers -- Ensure x-api-key is included in the auth request header.

Validation Snippet

Use the following snippet to quickly verify your credentials are working:

Python

import os
import requests

resp = requests.post(
    "https://api.alpha-sense.com/auth",
    headers={
        "x-api-key": os.environ["ALPHASENSE_API_KEY"],
    },
    data={
        "grant_type": "password",
        "username": os.environ["ALPHASENSE_EMAIL"],
        "password": os.environ["ALPHASENSE_PASSWORD"],
        "client_id": os.environ["ALPHASENSE_CLIENT_ID"],
        "client_secret": os.environ["ALPHASENSE_CLIENT_SECRET"],
    },
)

if resp.status_code == 200:
    token = resp.json()["access_token"]
    print("Auth successful. Token starts with:", token[:20])
else:
    print(f"Auth failed: {resp.status_code} — {resp.text}")

JavaScript

const resp = await fetch('https://api.alpha-sense.com/auth', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.ALPHASENSE_API_KEY,
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'password',
    username: process.env.ALPHASENSE_EMAIL,
    password: process.env.ALPHASENSE_PASSWORD,
    client_id: process.env.ALPHASENSE_CLIENT_ID,
    client_secret: process.env.ALPHASENSE_CLIENT_SECRET,
  }),
})

if (resp.ok) {
  const {access_token} = await resp.json()
  console.log('Auth successful. Token starts with:', access_token.slice(0, 20))
} else {
  console.error(`Auth failed: ${resp.status} — ${await resp.text()}`)
}

GenSearch Issues

• Empty markdown -- The search is still processing (progress < 1.0). Poll again until progress reaches 1.0.
• NO_DOCS error -- Rephrase your query, broaden the time range, or check whether the topic is covered in your available content.
• Slow response -- This is expected for certain modes. auto typically takes 30-90 seconds, thinkLonger takes 60-90 seconds, and deepResearch can take 3-5 minutes.
• Partial results -- If progress stalls before reaching 1.0, wait longer. The maximum timeout is approximately 10 minutes.

Streaming Issues

• No data received -- Verify the Accept header is set to multipart/mixed;subscriptionSpec=1.0.
• Boundary parse error -- Extract the boundary string from the Content-Type response header correctly. The server returns a header like Content-Type: multipart/mixed; boundary=--- and you must use that exact boundary value when splitting parts.
• Connection drops -- Implement reconnection logic in your client. Handle ChunkedEncodingError (Python requests) or equivalent exceptions in your HTTP library gracefully.

MCP Server Issues

• Server won't start -- Check that your Python version is 3.10 or higher. Verify the mcp package is installed (pip install mcp).
• Auth failures in MCP -- Verify that all required environment variables (ALPHASENSE_API_KEY, ALPHASENSE_EMAIL, ALPHASENSE_PASSWORD, ALPHASENSE_CLIENT_ID, ALPHASENSE_CLIENT_SECRET) are set correctly in your shell or MCP client configuration.
• Tool not found -- Ensure the MCP server is properly configured in your MCP client's settings file and that the server process is running.

Debug Checklist

Follow these steps in order when diagnosing an issue:

1. Verify credentials are correct -- Run the auth validation snippet above.
2. Check token expiration -- Tokens have a 24-hour lifetime. Re-authenticate if yours has expired.
3. Verify headers -- Ensure your requests include x-api-key, clientid, and Authorization: Bearer <token>.
4. Check GraphQL syntax -- Use the Explorer at /explorer to test your queries interactively.
5. Monitor the progress field -- When polling, check that progress is advancing toward 1.0.
6. Check the error field -- Inspect the error field in the conversation response for codes like NO_DOCS or TIMEOUT.
7. Review rate limits -- Credit limits and polling rates are determined by your commercial agreement. Exceeding your limits returns a 429 status.

Security Best Practices

• Never hardcode credentials in source code.
• Use environment variables or a secret manager to store sensitive values.
• Rotate API keys periodically.
• Store tokens securely and never log them.
• Use HTTPS for all API calls.
• Implement token refresh logic before the token expires to avoid interruptions.

Getting Help

Support

For API support, contact support@alpha-sense.com

Include in your support request:

• Your client ID (not your secret)
• The conversation ID (if applicable)
• The error message or HTTP status code
• Timestamp of the issue

Related Pages

For more details on specific topics covered here, see Authentication and Credits & Rate Limits.