Errors

Refusals are HTTP statuses on the call that was refused. Nothing is started and nothing is billed unless the POST answered 202.

Status	When	Body
`400`	`q` is present but only whitespace.	`{"detail": "Empty query"}`
`401`	No credential, or one that does not resolve.	`{"detail": "Missing credentials"}` when the `Authorization` header is absent or carries nothing after the scheme; `{"detail": "Invalid credentials"}` when the credential does not resolve to an account.
`402`	Your available balance cannot cover the reservation.	See below. Nothing was started.
`403`	The account behind the credential is closed.	`{"detail": "Account disabled"}`
`404`	The run is not yours, does not exist, or the id is malformed.	`{"detail": "Unknown search."}` All three answer identically on purpose: a run id is not a way to discover another account’s searches.
`422`	A field failed validation: `q` shorter than 3 or longer than 2000 characters, `target` outside 1–50, a negative `since`.	The standard validation body, a `detail` array naming the field that failed. Nothing was reserved.
`500`	The credential could not be looked up, or the reservation could not be opened.	`{"detail": "Internal server error"}` or `{"detail": "The reservation for this search could not be opened."}`. Both are safe to retry once.

Check what you sent before retrying a 401: an API key starts lf_live_ and a session token starts eyJ. A 403 and a 422 will answer the same way for ever, so fix the request rather than repeating it.

`402 Payment Required`

This is the ordinary out-of-funds signal, not a fault. A search holds

5.00 of your balance before it does any work, so a caller with

2.00 is refused up front rather than finding out after the providers have been paid.

{
  "detail": {
    "error": "insufficient_balance",
    "message": "This search needs $5.00 available. You have $2.00.",
    "availableMicrousd": 2000000,
    "availableUsd": "2.000000",
    "heldMicrousd": 1000000,
    "neededMicrousd": 5000000,
    "neededUsd": "5.000000"
  }
}

availableMicrousd is what you may spend, which is your balance minus heldMicrousd, the part already committed to runs in flight. neededMicrousd is the reservation, not the price of the search. The three *Microusd fields are integers in micro-USD; the two *Usd fields are the same figures as strings.

Do not retry a 402 on a timer. Nothing about the request was wrong, so a retry fails identically until the balance changes. It changes in two ways: a top-up, or a run in flight finishing and releasing its hold. Branch on error == "insufficient_balance", surface the message, and either wait for a run to land or send the user to top up. A retry loop here burns quota and tells the user nothing.

When the search itself fails

A run that was accepted and then failed is not an HTTP error anywhere: the POST already returned 202. It shows up as an error event in the stream, followed by cost, usage and done, and the run lands with status: "error".

Situation	What you see
The search could not finish	`error` with a short message, then `cost`, `usage` and `done`. `status` is `error`.
You called stop	`final` with `stopped: true`, then `cost` at stage `Stopped`, `usage` and `done` with `stopped: true`. `status` is `stopped`.
The balance ran out mid-run, or the run hit its ceiling	The same partial tail as a stop. `status` is `budget_exhausted`. You are charged for what it spent.
The run outlived its deadline, or its process went away	`status` is `interrupted`, with `stopReason: "deadline"` in the first case. There may be no tail at all, so `result` can be `null`. `where` says how far it got.

The 402 case leaves one more trace worth knowing about: a run row with status: "error" and no events, because the run document is written before the reservation is attempted. It will appear in GET /v1/searches.

Key management errors

Status	When	Body
`401`	`POST`, `GET` or `DELETE /api/keys` called with an API key instead of a session token, or with no token.	An API key gets `{"detail": "Invalid token"}`, because it is not a session token and these routes take nothing else. A missing or empty header gets `{"detail": "Missing bearer token"}`, and a valid token for an account that no longer exists gets `{"detail": "Unknown user"}`. The refusal is deliberate; see Access.
`403`	The account is closed.	`{"detail": "Account is deleted"}`
`404`	The key id is not yours, does not exist, or is already revoked.	`{"detail": "Key not found"}`
`422`	`name` is missing, empty, or longer than 100 characters.	The standard validation body.
`400`	`name` is present but only whitespace.	`{"detail": "name is required"}`

Get started

API reference

Integrate

`402 Payment Required`

When the search itself fails

Key management errors

​402 Payment Required

​When the search itself fails

​Key management errors

`402 Payment Required`

When the search itself fails

Key management errors