Errors
Every error has the same four fields, so an agent can recover without reading the docs.
Planned for the research API (milestone M5). Until it ships, the search and record endpoints return 404 not_found. Keys and GET /v1/key work now.
Shape
{
"error": {
"code": "living_person_blocked",
"message": "This search is about someone who may be alive.",
"docs_url": "https://api.lineage.rexstjohn.com/docs/errors#living_person_blocked",
"fix": "Add a death date, or a birth year more than 110 years ago. Lineage treats anyone else as living."
}
}code is stable and safe to branch on. message is for people. fix says what to change in the next request. docs_url links to the row below.
Codes
| Code | Status | Charged | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in message, then retry |
invalid_api_key | 401 | No | Send a valid key in the Authorization header |
api_key_revoked | 401 | No | Create a new key on the keys page |
insufficient_credits | 402 | No | Add credits, or lower budget_credits |
budget_exceeded | 402 | Up to the budget | Partial results are included; raise budget_credits to go further |
not_found | 404 | No | Check the path and the id; search and record ids start with srch_ and rec_ |
method_not_allowed | 405 | No | Use a method from the Allow header |
living_person_blocked | 422 | No | Add a death date or a birth year more than 110 years ago; anyone else is treated as living |
rate_limited | 429 | No | Wait retry_after seconds, then retry |
not_configured | 503 | No | The server is missing a setting; try again later |
Not an error: skipped sources
When a source is down or rate limited, the search continues with the next source for that record type. The skipped source is listed in skipped with its reason, and you are not charged for it.