Skip to content

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."
}
}
  • code is stable and machine-readable. Branch on it.
  • message is 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.

StatusCodeWhen
400bad_requestA 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.
401unauthenticatedNo Authorization header, or one that is not Bearer <key>. Answered with WWW-Authenticate: Bearer realm="alethman".
401invalid_keyThe 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".
403insufficient_scopeThe key is valid but does not carry the scope this endpoint needs. The message names the scope.
404not_foundNo story, report or source with that id in this workspace, or a story outside the workspace's sectors and states.
409workspace_not_readyThe workspace has not been set up yet. An owner or admin finishes the setup walkthrough in the dashboard first.
422unprocessablePOST /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.
429rate_limitedMore 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).
500internalSomething 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.

GET /api/v1/signals?limit=0
{
"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."
}
}
}

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.

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 random
import 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")

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.