Errors

Written for the caller who has to decide what to do next, not just for the one reading a log.

Status	Cause	What to do
400	A parameter is malformed — an unknown `sort`, a `date` outside the preset list, an unparseable `from`.	Do not retry. The `detail` field names the parameter and lists the accepted values. Fix and re-issue.
404	Only from `/v1/article`: no article with that exact URL.	Do not retry. Fall back to `/v1/search` on the title.
422	A parameter is out of range — `size>100`, `offset>9900`, a non-integer where a number was expected.	Do not retry. Clamp the value. For deep paging see pagination.
429	Too many requests from one IP address.	Back off and retry. Start at one second and double, up to a minute. Serialise your requests rather than firing them in parallel.
502	The search backend returned an error.	Retry once after two seconds. If it persists, the query itself may be the problem — simplify it.
503	The search backend is unreachable.	Do not retry immediately. Wait at least ten seconds. Check /status.

Error shape

json

{
  "detail": "sort must be one of: date, date_asc, crawled, crawled_asc, relevance"
}

Always a JSON object with a single detail string, human-readable and specific enough to act on. Validation failures from the framework use the standard detail array with loc, msg and type.

Retry policy in one rule

4xx means you are wrong; 5xx means we are. Never retry a 4xx unchanged — it will fail identically forever. Always back off before retrying a 5xx.

Things that are not errors

Zero results. 200 with an empty results array. Usually the filters are too narrow or the date range predates the 30-day window.
Unknown parameters. Ignored silently, so a typo in a parameter name returns unfiltered results rather than an error. Check your spelling if a filter appears to do nothing.
total stuck at exactly 10000. Expected: the count is capped. total_is_lower_bound will be true. Use /v1/stats for an exact figure.