Errors and Limits
Error format
Every error from the API has the same JSON shape:
{
"error": {
"code": "INVALID_REQUEST",
"message": "Missing required parameter: 'input.text'.",
"type": "bad_request",
"param": "input.text",
"request_id": "req_3f9c0a1b2c3d4e5f60718293",
"retryable": false,
"details": {}
}
}
Branch on code and retryable. message is for people and its wording can change. param names
the field that caused the error, if any. request_id matches the X-Request-Id header; quote it
when you contact support.
Some errors come from the network layer in front of the API. They may have no JSON body and no
X-Request-Id:
429: a rate limit. The body is empty and there is noRetry-After. Wait the number of seconds inX-RateLimit-Reset, then send the request again. A refused create or follow-up started no turn.413: the request body is over 1 MiB.502,503, or504: retry reads. For a create or follow-up, check the session first.
Error codes
| Code | HTTP | Retry? | When |
|---|---|---|---|
INVALID_REQUEST | 400 | No | Bad JSON, missing or blank input.text, unknown field, bad limit or id, or a cursor the API didn't issue. |
UNSUPPORTED_OPERATION | 400 | No | A parameter that isn't supported, such as cursor on /messages. |
UNAUTHENTICATED | 401 | With a new token | The token is missing, expired, or invalid. |
ENTITLEMENT_REQUIRED | 403 | No | The user lacks SuperAnalyst or SuperAnalyst API access. |
NOT_FOUND | 404 | No | Unknown path, or a session, artifact, or file you can't see. |
SESSION_BUSY | 409 | After the turn ends | A follow-up sent while the session is queued or in_progress. |
INTERNAL_ERROR | 500 | Yes | Unexpected server error. |
UPSTREAM_ERROR | 502 | Yes | SuperAnalyst couldn't complete the request, or a file can't be read. |
UPSTREAM_CONTRACT | 502 | No | SuperAnalyst rejected the request. Contact support with the request_id. |
RUNTIME_UNAVAILABLE | 503 | After Retry-After | Temporarily unavailable, most often while a new user's workspace is set up. |
UPSTREAM_TIMEOUT | 504 | Check the session first | SuperAnalyst didn't answer in time. The turn may still be running. |
Three codes appear inside a 200 response, not as an HTTP status:
RUNTIME_ERRORin a session'serror, or aturn.failedevent: the turn ended without an answer. Ask again.RUNTIME_TIMEOUTin a session'serror, or aturn.timed_outevent: the turn ran out of time, or the stream stopped watching it (retryable: false). Check the session, and ask again only if itsstatusistimed_out.FILE_TOO_LARGEin a content response withdelivery: "too_large": the file is over the download size limit.
Retrying safely
- Retry only errors marked retryable, with exponential backoff and a cap.
- Wait the number of seconds in
Retry-Afterwhen the response has it, or inX-RateLimit-Reseton a429. - Never blindly resend a create or follow-up. These requests start turns and aren't idempotent.
After a
504, a timeout, or a dropped connection, check the session first. - Resending a create or follow-up is safe after
RUNTIME_UNAVAILABLEor a429, because no turn started. - Some
502s don't clear with retries, such as an old sessionscursoror an unreadable file. Start the list again, or skip the file. See Pagination.
- Python
- JavaScript
import random
import time
import requests
EDGE_RETRYABLE = {429, 502, 503, 504}
def call(method, url, attempts=5, **kwargs):
"""Send a request, and retry it only when that is safe."""
kwargs.setdefault("timeout", 60)
for attempt in range(attempts):
response = requests.request(method, url, **kwargs)
if response.ok:
return response
if response.headers.get("Content-Type", "").startswith("application/json"):
error = response.json()["error"]
else:
error = {"code": response.status_code, "retryable": response.status_code in EDGE_RETRYABLE}
no_turn_started = response.status_code == 429 or error["code"] == "RUNTIME_UNAVAILABLE"
if attempt == attempts - 1 or not error["retryable"] or (method != "GET" and not no_turn_started):
raise RuntimeError(f"{error['code']}: {error.get('message')} ({error.get('request_id')})")
wait = response.headers.get("Retry-After") or response.headers.get("X-RateLimit-Reset", "")
time.sleep(int(wait) + random.random() if wait.isdigit() else 2**attempt + random.random())
const EDGE_RETRYABLE = [429, 502, 503, 504]
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
// Send a request, and retry it only when that is safe.
async function call(method, url, init = {}, attempts = 5) {
for (let attempt = 0; ; attempt++) {
const response = await fetch(url, {...init, method})
if (response.ok) return response
const isJson = response.headers.get('Content-Type')?.startsWith('application/json')
const error = isJson
? (await response.json()).error
: {code: response.status, retryable: EDGE_RETRYABLE.includes(response.status)}
const noTurnStarted = response.status === 429 || error.code === 'RUNTIME_UNAVAILABLE'
if (attempt === attempts - 1 || !error.retryable || (method !== 'GET' && !noTurnStarted)) {
throw new Error(`${error.code}: ${error.message} (${error.request_id})`)
}
const wait =
response.headers.get('Retry-After') ?? response.headers.get('X-RateLimit-Reset') ?? ''
const seconds = /^\d+$/.test(wait) ? Number(wait) + Math.random() : 2 ** attempt + Math.random()
await sleep(seconds * 1000)
}
}
Retry-After is usually a number of seconds. If it is a date instead, both helpers fall back to
backoff. Both add up to a second of random delay, so retries from many clients don't arrive
together.
Pagination
| Endpoint | limit default | limit range | Paging |
|---|---|---|---|
GET /sessions | 20 | 1–200 | cursor and next_cursor |
GET /sessions/{id}/artifacts | 20 | 1–100 | cursor and next_cursor |
GET /files | 20 | 1–100 | cursor and next_cursor |
GET /sessions/{id}/messages | 200 | 1–200 | None. Keeps the newest messages |
Pass next_cursor back unchanged as cursor, and stop when it is null. A short page is not the
end. A limit out of range returns 400. Lists have no total count, and items can shift between
pages while you page.
A cursor the API didn't issue, or one that is too old, is handled differently on each list:
| Endpoint | A cursor the API didn't issue | A cursor that is too old |
|---|---|---|
GET /sessions | 400 | 502 that retries don't clear. Start again. |
GET /sessions/{id}/artifacts | 400 | Doesn't expire. Items can shift between pages. |
GET /files | Ignored | Ignored: the list starts again from the first page |
Timeouts and limits
- A question usually takes a few minutes. A report, deck, or dashboard can take 25 minutes or more, longer than one request or stream lasts. Check the session or reattach until the turn ends.
- A request can run for up to 16 minutes (960 seconds). Set stream read timeouts at least that high.
- A single event stream stays open for up to 15 minutes, with a heartbeat about every 10 seconds.
- An access token lasts about 30 minutes.
- A new user's first request can return
503for 1–2 minutes. - A new entitlement can take up to 5 minutes to apply.
- Input is text only, and a session runs one turn at a time.
- Requests aren't idempotent. Every create or follow-up starts a turn.
- A request body can be up to 1 MiB.
- Requests are rate-limited. Over the limit, the API returns
429(see Error format). - Cancelling stops a turn but keeps the session. Sessions can't be deleted and have no timestamps.
- A transcript returns at most 200 messages.
- Downloads are limited to about 2 MB per file.
- Browser cross-origin requests aren't supported. Call the API from your backend.
Common problems
| Symptom | Fix |
|---|---|
| Token request fails | See When authentication fails. |
401 right after a successful token exchange | Get the token from https://auth.research.alpha-sense.com/oauth/token. |
503 RUNTIME_UNAVAILABLE on first use | Wait the number of seconds in Retry-After, then resend. |
404 for a session you just created | URL-encode the session id exactly once. |
409 SESSION_BUSY | Wait for the current turn to end, or cancel it. |
| Two answers for one question | A create or follow-up was resent after a timeout. Check the session before resending. |
| A follow-up returns the previous answer | Wait for an answer newer than the previous one. See Ask a follow-up. |
| The last question has no answer | Its turn was cancelled or failed. Check session_status, then ask again as a follow-up. |
| Two questions get one combined answer | The second was sent right after the first. Send one follow-up at a time, and wait for its answer. |
| A follow-up stream shows no events | Its turn ended before you attached. Attach first, then send it. See Stream a follow-up. |
| A stream closes with no final event | Attach again and check status. See Reconnecting. |
429 with an empty body | Wait the number of seconds in X-RateLimit-Reset, then resend. |
| Nothing streams for a long time | The answer arrives near the end of the turn. Show progress.updated labels, and use curl -N. |
| The stream is cut off by your client | Raise the read timeout to the request limit above. |
| The answer is missing after a reconnect | Read it from GET /sessions/{session_id}/messages. |
| The turn keeps running after you close the stream | Call POST /sessions/{session_id}/cancel. |
| A downloaded file won't open | Decode content_base64 before you save it. |
| A browser shows a CORS error | Call the API from your backend. |
If you're still stuck, contact support@alpha-sense.com with the request_id. Never send tokens
or secrets.