Errors
Every error is JSON with the same shape, whatever went wrong:
{ "error": { "code": "bad_request", "message": "limit must be a whole number from 1 to 200." }}codeis stable and machine-readable. Branch on it.messageis one sentence for a person: what was wrong and what to do. It may be reworded; never parse it.
Errors are never cached (Cache-Control: no-store). Status codes follow HTTP: 4xx means fix the request, 5xx means retry.
Every error
Section titled “Every error”| Status | Code | When |
|---|---|---|
| 400 | bad_request | A parameter is out of range or not one of the allowed values, a cursor is not one the API gave, or a POST body is not valid. The message names the parameter and what it accepts. |
| 401 | unauthenticated | No Authorization header, or one that is not Bearer <key>. Answered with WWW-Authenticate: Bearer realm="alethman". |
| 401 | invalid_key | The key is unknown, revoked or expired, its workspace is suspended, or the person who made it is no longer an active owner or admin. Answered with WWW-Authenticate: Bearer realm="alethman", error="invalid_token". |
| 403 | insufficient_scope | The key is valid but does not carry the scope this endpoint needs. The message names the scope. |
| 404 | not_found | No story, report or source with that id in this workspace, or a story outside the workspace's sectors and states. |
| 409 | workspace_not_ready | The workspace has not been set up yet. An owner or admin finishes the setup walkthrough in the dashboard first. |
| 422 | unprocessable | POST /sources could not follow the address: it is not a feed, could not be read, is already a source, or the workspace already follows 50 sources of its own. |
| 429 | rate_limited | More than 120 requests in a minute on one key (wait for Retry-After seconds), or more than 30 failed key attempts in a minute from one address (wait 60 seconds). |
| 500 | internal | Something failed on Alethman's side. Retry with backoff; if it persists, write to Alethman with the time of the request. |
A request meets the checks in this order: the key (401, or the bad-key limit’s 429 once an address has sent 30 bad keys in a minute; a valid key is never refused by it), then the scope (403), then the key’s rate (429), then the workspace (409), then the request itself (400, 404, 422). So a 403 or a 401 never counts against the 120 a minute, and only responses from the rate check on carry the rate-limit headers.
What each looks like
Section titled “What each looks like”{ "request": "GET /api/v1/signals?limit=0", "status": 400, "headers": { "content-type": "application/json", "cache-control": "no-store", "x-ratelimit-limit": "120", "x-ratelimit-remaining": "107", "x-ratelimit-reset": "1795238160" }, "body": { "error": { "code": "bad_request", "message": "limit must be a whole number from 1 to 200." } }}{ "request": "GET /api/v1/signals", "status": 401, "headers": { "content-type": "application/json", "cache-control": "no-store", "www-authenticate": "Bearer realm=\"alethman\"" }, "body": { "error": { "code": "unauthenticated", "message": "Send your key as: Authorization: Bearer alm_live_…" } }}{ "request": "POST /api/v1/sources", "status": 403, "headers": { "content-type": "application/json", "cache-control": "no-store" }, "body": { "error": { "code": "insufficient_scope", "message": "This key does not carry the sources:write scope." } }}{ "request": "GET /api/v1/stories/1", "status": 404, "headers": { "content-type": "application/json", "cache-control": "no-store", "x-ratelimit-limit": "120", "x-ratelimit-remaining": "106", "x-ratelimit-reset": "1795238160" }, "body": { "error": { "code": "not_found", "message": "No story with that id." } }}{ "status": 429, "headers": { "retry-after": "23", "x-ratelimit-limit": "120", "x-ratelimit-remaining": "0", "x-ratelimit-reset": "1795238160" }, "body": { "error": { "code": "rate_limited", "message": "120 requests a minute per key. Wait for the window to reset." } }}The 400 messages
Section titled “The 400 messages”A 400 bad_request names the parameter and what it accepts, so the message is the fix:
| Message | Cause |
|---|---|
limit must be a whole number from 1 to 200. |
A number out of range or not a whole number. The range is the parameter’s. |
order must be one of: voices, risk, recent. |
A value that is not one of the allowed ones. |
since must be an ISO 8601 time, for example 2026-09-28T09:00:00Z. |
A time that does not parse. |
q is longer than 120 characters. |
Text over the parameter’s length. |
cursor is not valid. Use the next_cursor from a previous page. |
A cursor the API did not give. |
source must be a source id. |
source on /sources/items is not a UUID. |
POST /sources has its own body errors; see Add a source.
Retrying
Section titled “Retrying”| Status | Retry? | How |
|---|---|---|
| 400, 401, 403, 404, 409, 422 | No | The same request fails the same way. Fix it first. |
| 429 | Yes | Wait Retry-After seconds, then retry. |
| 500 | Yes | Exponential backoff with jitter: 1 s, 2 s, 4 s, up to about a minute. |
| Network error, 502, 503, 504 | Yes | As for 500. These come from the network or a deploy, not the API, and may not carry the JSON body. |
Every endpoint that reads is safe to retry. POST /sources is safe too: adding a feed you already follow answers 422 (“That feed is already one of your sources.”), never a duplicate.
import randomimport time
import requests
def call(s: requests.Session, url: str, **params): for attempt in range(6): try: r = s.get(url, params=params, timeout=30) except requests.ConnectionError: r = None if r is not None and r.status_code < 500 and r.status_code != 429: if not r.ok: err = r.json()["error"] raise RuntimeError(f"{r.status_code} {err['code']}: {err['message']}") return r.json() wait = int(r.headers.get("Retry-After", 0)) if r is not None and r.status_code == 429 else 2**attempt time.sleep(wait + random.random()) raise RuntimeError("gave up after 6 attempts")async function call(url, headers) { for (let attempt = 0; attempt < 6; attempt++) { let res = null; try { res = await fetch(url, { headers }); } catch {} if (res && res.status < 500 && res.status !== 429) { if (!res.ok) { const { error } = await res.json(); throw new Error(`${res.status} ${error.code}: ${error.message}`); } return res.json(); } const wait = res?.status === 429 ? Number(res.headers.get("Retry-After") ?? 1) : 2 ** attempt; await new Promise((r) => setTimeout(r, (wait + Math.random()) * 1000)); } throw new Error("gave up after 6 attempts");}When it persists
Section titled “When it persists”A 500 that keeps coming back is ours to fix. Write to Alethman with the time of the request (UTC), the endpoint and the parameters. Never send the key.