Skip to main content

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 no Retry-After. Wait the number of seconds in X-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, or 504: retry reads. For a create or follow-up, check the session first.

Error codes​

CodeHTTPRetry?When
INVALID_REQUEST400NoBad JSON, missing or blank input.text, unknown field, bad limit or id, or a cursor the API didn't issue.
UNSUPPORTED_OPERATION400NoA parameter that isn't supported, such as cursor on /messages.
UNAUTHENTICATED401With a new tokenThe token is missing, expired, or invalid.
ENTITLEMENT_REQUIRED403NoThe user lacks SuperAnalyst or SuperAnalyst API access.
NOT_FOUND404NoUnknown path, or a session, artifact, or file you can't see.
SESSION_BUSY409After the turn endsA follow-up sent while the session is queued or in_progress.
INTERNAL_ERROR500YesUnexpected server error.
UPSTREAM_ERROR502YesSuperAnalyst couldn't complete the request, or a file can't be read.
UPSTREAM_CONTRACT502NoSuperAnalyst rejected the request. Contact support with the request_id.
RUNTIME_UNAVAILABLE503After Retry-AfterTemporarily unavailable, most often while a new user's workspace is set up.
UPSTREAM_TIMEOUT504Check the session firstSuperAnalyst didn't answer in time. The turn may still be running.

Three codes appear inside a 200 response, not as an HTTP status:

  • RUNTIME_ERROR in a session's error, or a turn.failed event: the turn ended without an answer. Ask again.
  • RUNTIME_TIMEOUT in a session's error, or a turn.timed_out event: the turn ran out of time, or the stream stopped watching it (retryable: false). Check the session, and ask again only if its status is timed_out.
  • FILE_TOO_LARGE in a content response with delivery: "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-After when the response has it, or in X-RateLimit-Reset on a 429.
  • 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_UNAVAILABLE or a 429, because no turn started.
  • Some 502s don't clear with retries, such as an old sessions cursor or an unreadable file. Start the list again, or skip the file. See Pagination.
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())

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​

Endpointlimit defaultlimit rangePaging
GET /sessions201–200cursor and next_cursor
GET /sessions/{id}/artifacts201–100cursor and next_cursor
GET /files201–100cursor and next_cursor
GET /sessions/{id}/messages2001–200None. 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:

EndpointA cursor the API didn't issueA cursor that is too old
GET /sessions400502 that retries don't clear. Start again.
GET /sessions/{id}/artifacts400Doesn't expire. Items can shift between pages.
GET /filesIgnoredIgnored: 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 503 for 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​

SymptomFix
Token request failsSee When authentication fails.
401 right after a successful token exchangeGet the token from https://auth.research.alpha-sense.com/oauth/token.
503 RUNTIME_UNAVAILABLE on first useWait the number of seconds in Retry-After, then resend.
404 for a session you just createdURL-encode the session id exactly once.
409 SESSION_BUSYWait for the current turn to end, or cancel it.
Two answers for one questionA create or follow-up was resent after a timeout. Check the session before resending.
A follow-up returns the previous answerWait for an answer newer than the previous one. See Ask a follow-up.
The last question has no answerIts turn was cancelled or failed. Check session_status, then ask again as a follow-up.
Two questions get one combined answerThe 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 eventsIts turn ended before you attached. Attach first, then send it. See Stream a follow-up.
A stream closes with no final eventAttach again and check status. See Reconnecting.
429 with an empty bodyWait the number of seconds in X-RateLimit-Reset, then resend.
Nothing streams for a long timeThe answer arrives near the end of the turn. Show progress.updated labels, and use curl -N.
The stream is cut off by your clientRaise the read timeout to the request limit above.
The answer is missing after a reconnectRead it from GET /sessions/{session_id}/messages.
The turn keeps running after you close the streamCall POST /sessions/{session_id}/cancel.
A downloaded file won't openDecode content_base64 before you save it.
A browser shows a CORS errorCall the API from your backend.

If you're still stuck, contact support@alpha-sense.com with the request_id. Never send tokens or secrets.