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

Which auth flow are you using?

• Username and password — authenticate at POST https://api.alpha-sense.com/auth. See Authentication (Username & Password).
• SSO (refresh token) — exchange your refresh token at POST https://auth.research.alpha-sense.com/oauth/token. See SSO Authentication (beta; enabled by your account team).

Username and password

• Token expired — Re-authenticate at /auth or use your refresh token. Access tokens last 24 hours (expires_in: 86400).
• Wrong credentials — Verify your email, password, client_id, client_secret, and api_key.
• Missing headers — Ensure x-api-key is included in the auth request header.

SSO (refresh token grant)

• 401 after SSO rollout — Confirm you are calling auth.research.alpha-sense.com/oauth/token, not api.alpha-sense.com/auth.
• Invalid refresh token — Generate a new refresh token from the API Keys page in the web app.
• Missing API Keys page — Your account needs an API license and the SSO beta flow enabled; contact your account team.

Validation Snippet (username and password)

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.

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 (Username & Password), SSO Authentication, and Credits & Rate Limits.