FocusAlphaDocs
Get key
API Reference

Errors

Every error returns the same JSON envelope with the right HTTP status code, so you can handle failures uniformly.

Error envelope#

All errors share one shape. success is always false, and the error object carries the status code, a human-readable message, the error name, the request path, and a timestamp.

error.json
{
  "success": false,
  "error": {
    "statusCode": 401,
    "message": "Invalid or missing API key",
    "error": "Unauthorized",
    "path": "/v1/retrieve",
    "timestamp": "2026-05-30T12:00:00.000Z"
  }
}

Status codes#

400Bad Requestoptional
The request body failed validation — a missing or over-long query, an out-of-range top_k, an unknown field, or a malformed filter. Note that tickers, year, quarter, and source_types must be nested under a filters object, not sent as top-level fields. The message names the offending field.
401Unauthorizedoptional
The API key is missing, malformed, unknown, or revoked. See Authentication.
404Not Foundoptional
The requested resource doesn’t exist — for example a document id that isn’t in the corpus. Don’t retry without changing the id.
429Too Many Requestsoptional
You exceeded either your per-minute rate limit or your monthly quota. Back off and retry. See Rate Limits & Quotas.
500Internal Server Erroroptional
Something failed on our side (including an upstream retrieval or database failure). The request was not billed. Safe to retry with backoff.
Why a 500 and not a 401 on outages
Authentication fails closed: if we can’t verify your key because of an internal/database problem, you get a 500, never a misleading 401. A 401 always means the key itself was rejected.

Handling errors#

Check the HTTP status first, then read error.message for specifics. Retry 429 and 500 with exponential backoff; do not retry 400 or 401 without changing the request or key.

handle.ts
const res = await fetch(url, options);

if (!res.ok) {
  const { error } = await res.json();
  if (res.status === 429 || res.status >= 500) {
    // transient — retry with backoff
    await backoffAndRetry();
  } else {
    // 400 / 401 — fix the request or the key
    throw new Error(`${error.statusCode}: ${error.message}`);
  }
}