# Errors

One error object for every failure, with what to do. A failed call costs nothing.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Send your API key as `Authorization: Bearer <key>`; it is on https://app.lobstr.io/dashboard/api",
    "param": null,
    "doc_url": "https://docs.lobstr.io/errors#missing_api_key",
    "request_id": "req_t7nhs6wqq5bojctezxhjqjf45e",
    "retryable": false
  }
}
```

<ResponseField name="type" type="string">
Follows the HTTP status, to branch on: `invalid_request_error` (400, 404, 409, 410, 422), `authentication_error` (401), `billing_error` (402), `rate_limit_error` (429), `site_error` (408, 424, 503), `api_error` (500).
</ResponseField>
<ResponseField name="code" type="string">
What happened, exactly: the list below.
</ResponseField>
<ResponseField name="message" type="string">
What to do, in a sentence a person or an agent can follow.
</ResponseField>
<ResponseField name="param" type="string">
The option at fault, as `options.place`, or `null`.
</ResponseField>
<ResponseField name="retryable, retry_after" type="boolean, integer">
Whether the same call can work later, and in how many seconds (also in the `Retry-After` header).
</ResponseField>

Nothing is charged for a call that fails, whoever's fault it is.

## Every call

<ErrorCode code="missing_api_key" status="401">
No `Authorization` header: send `Authorization: Bearer <key>`.
</ErrorCode>
<ErrorCode code="invalid_api_key" status="401">
The key was mistyped or changed: copy it again from [the app](https://app.lobstr.io/dashboard/api).
</ErrorCode>
<ErrorCode code="insufficient_credits" status="402">
The call costs more credits than are left. The message says both; [plans](https://app.lobstr.io/dashboard/plans).
</ErrorCode>
<ErrorCode code="unknown_operation" status="404">
No such operation on this source: `GET /v2/catalog?source=...` lists them.
</ErrorCode>
<ErrorCode code="timeout" status="408" retryable>
The site did not answer in time. Retry, or raise `timeout_s` up to the operation's maximum.
</ErrorCode>
<ErrorCode code="idempotency_conflict" status="409">
This `Idempotency-Key` was used with another body: use a new key for a new call.
</ErrorCode>
<ErrorCode code="idempotency_in_flight" status="409" retryable>
The first call with this key still runs: retry with the same key in a few seconds.
</ErrorCode>
<ErrorCode code="invalid_body" status="422">
The body is not what `POST /v2/run` takes; `param` says where.
</ErrorCode>
<ErrorCode code="invalid_options" status="422">
An option does not fit the operation's contract; `param` names it, the message says what it takes.
</ErrorCode>
<ErrorCode code="invalid_fields" status="422">
A field asked in `fields` is not in the records; the message lists those that are.
</ErrorCode>
<ErrorCode code="invalid_limit" status="400, 422">
`limit` out of its range (1 to 100 on `GET /v2/runs`), or sent to an operation that answers one record.
</ErrorCode>
<ErrorCode code="invalid_idempotency_key" status="400">
`Idempotency-Key` takes 1 to 255 printable characters, no spaces; a UUID is fine.
</ErrorCode>
<ErrorCode code="concurrency_limit" status="429" retryable>
Your plan's calls at a time are all running: [Limits](https://staging.docs.lobstr.io/limits).
</ErrorCode>
<ErrorCode code="internal_error" status="500" retryable>
Something broke on our side: retry, and quote the `request_id` if it happens again.
</ErrorCode>
<ErrorCode code="balance_unavailable" status="503" retryable>
Your balance could not be read: nothing ran, retry in a few seconds.
</ErrorCode>
<ErrorCode code="accounts_unavailable" status="503" retryable>
Your connected accounts could not be read: nothing ran, retry in a few seconds.
</ErrorCode>
<ErrorCode code="service_busy" status="503" retryable>
Too many calls at once on your account: retry in a few seconds.
</ErrorCode>

## Connected accounts

When `POST /v2/accounts` connects an account ([Accounts](https://staging.docs.lobstr.io/accounts)):

<ErrorCode code="invalid_cookies" status="422">
The site did not accept these cookies, or they hold no login: copy them again from a browser where you are logged in.
</ErrorCode>
<ErrorCode code="country_required" status="422">
The country this call comes from could not be told: send `country`, the one you use the account from.
</ErrorCode>
<ErrorCode code="invalid_country" status="422">
This site's accounts go out from one country (Leboncoin: FR): leave `country` out or send that one.
</ErrorCode>
<ErrorCode code="account_not_found" status="404">
No connected account of yours has this id: `GET /v2/accounts` lists them.
</ErrorCode>

## Your calls

When `GET /v2/runs` reads them back ([Run an operation](https://staging.docs.lobstr.io/run#your-calls)):

<ErrorCode code="run_not_found" status="404">
No call of yours has this id; calls are kept 90 days.
</ErrorCode>
<ErrorCode code="response_not_kept" status="404">
This call's whole answer was not kept: a failed call answered its error only, and `GET /v2/runs/{id}` has it.
</ErrorCode>
<ErrorCode code="response_expired" status="410">
Your plan keeps answers 7, 45 or 90 days, and this one's time is over.
</ErrorCode>
<ErrorCode code="invalid_date" status="400">
`created_after` and `created_before` take a date in UTC, as `2026-11-09T08:00:00Z`.
</ErrorCode>
<ErrorCode code="invalid_status" status="400">
`status` takes `succeeded` or `failed`.
</ErrorCode>
<ErrorCode code="invalid_via" status="400">
`via` takes `api`, `mcp` or `app`.
</ErrorCode>

## An operation's own

Each operation lists its errors on its page; here they all are, each once.

- `invalid_listing` (400): Pass a LaCentrale listing reference, numeric id or listing URL. From `lacentrale/listings/check`, `lacentrale/listings/get`, `leboncoin/listings/check`, `leboncoin/listings/get`, `leboncoin/phones/get`, `realtor/listings/get`, `seloger/listings/get`.
- `profile_protected` (403): This profile's posts are protected: X shows them to its followers only, and your connected X account does not follow it (not charged). From `x/tweets/list`.
- `listing_gone` (404): LaCentrale says this listing is unavailable or does not exist. From `lacentrale/listings/get`, `leboncoin/listings/get`, `seloger/listings/get`.
- `listing_not_found` (404): realtor.com knows no such listing (not charged). From `realtor/listings/get`.
- `place_not_found` (404): Google knows no such place (not charged). From `google_maps/places/get`, `realtor/listings/search`.
- `profile_not_found` (404): X has no profile with this handle (not charged). From `x/profiles/get`, `x/tweets/list`.
- `profile_unavailable` (404): X does not show this profile, suspended or withheld (not charged). From `x/profiles/get`, `x/tweets/list`.
- `account_unusable` (409): Leboncoin logged this account out. Connect it again with POST /v2/accounts and fresh cookies from a browser where you are logged in (the same login keeps its id). From `leboncoin/phones/get`, `x/profiles/get`, `x/tweets/list`, `x/tweets/search`.
- `account_required` (422): You have no connected Leboncoin account. Connect one with POST /v2/accounts {"site": "leboncoin", "cookies": ...}, the cookies of a browser where you are logged in to Leboncoin (https://docs.lobstr.io/accounts). From `leboncoin/phones/get`, `x/profiles/get`, `x/tweets/list`, `x/tweets/search`.
- `ambiguous_query` (422): This name matches several places; choose one and send its id as `place`. From `google_maps/places/get`.
- `invalid_cursor` (422): This cursor was not given by an answer; send `next` from the last answer as it is. From `google_maps/reviews/list`, `leboncoin/listings/search`.
- `invalid_edition` (422): An edition is COUNTRY:language, as Google News writes it: US:en, FR:fr. From `google_news/articles/search`.
- `invalid_max_pages` (422): `max_pages` takes 1 to 10. From `websites/contacts/get`.
- `invalid_place` (422): This place id or link does not say which place it is on Google's side; send its cid or its page's link. From `google_maps/places/get`, `google_maps/reviews/list`.
- `invalid_profile` (422): Pass a profile's handle (nasa, @nasa) or its address (https://x.com/nasa). From `x/profiles/get`, `x/tweets/list`.
- `invalid_query` (422): `query` takes 1 to 500 characters. From `google_news/articles/search`, `x/tweets/search`.
- `invalid_search` (422): Pass the continuation context unchanged from next, or omit search to start a new search. From `lacentrale/listings/search`, `seloger/listings/search`.
- `invalid_site` (422): `site` is a domain: reuters.com. From `google_news/articles/search`.
- `invalid_time` (422): `when` takes 1h, 1d or 7d; `after` and `before` are days (YYYY-MM-DD); not `when` with them. From `google_news/articles/search`.
- `invalid_url` (422): This is not a supported LaCentrale listing URL, or a filter or page is invalid. From `lacentrale/listings/search`, `leboncoin/listings/search`, `realtor/listings/search`, `seloger/listings/search`.
- `invalid_website` (422): The value is neither a website's address nor a domain. From `websites/contacts/get`.
- `other_site` (422): This listing is shown on another site than seloger.com (Belles Demeures, SeLoger Neuf). Not charged. From `seloger/listings/get`.
- `unexpected_answer` (424): Google answered in a shape we do not read yet; we are told and fix it, and it is not charged. Retrying now gives the same. From `google_maps/places/get`, `google_maps/places/search`, `google_maps/reviews/list`, `google_news/articles/search`, `lacentrale/listings/check`, `lacentrale/listings/get`, `lacentrale/listings/search`, `leboncoin/listings/check`, `leboncoin/listings/get`, `leboncoin/listings/search`, `realtor/listings/get`, `realtor/listings/search`, `seloger/listings/get`, `seloger/listings/search`, `x/profiles/get`, `x/tweets/list`, `x/tweets/search`.
- `website_unreachable` (424): The website did not answer: its domain has no server, it refused the connection, or its home page is missing. Not charged. From `websites/contacts/get`.
- `account_quota_exceeded` (429): Your Leboncoin accounts reached their calls for today; `retry_after` says when the day starts over (midnight UTC). From `leboncoin/phones/get`.
- `account_rate_limited` (429): Your Leboncoin accounts are paced at about one call a minute; `retry_after` says when the next slot opens. Retrying before then gets this same answer: nothing is queued. From `leboncoin/phones/get`, `x/profiles/get`, `x/tweets/list`, `x/tweets/search`.
- `blocked` (503): LaCentrale refused this request. Retry later; failed calls are free. From `lacentrale/listings/check`, `lacentrale/listings/get`.
- `ip_blocked` (503): LaCentrale refused the attempted IPs. Retry later; failed calls are free. From `lacentrale/listings/check`, `lacentrale/listings/get`.
- `site_challenge` (503): Google asked to prove a person is there; retry in a minute (not charged). From `google_news/articles/search`, `lacentrale/listings/search`, `leboncoin/listings/check`, `leboncoin/listings/get`, `leboncoin/listings/search`, `leboncoin/phones/get`, `realtor/listings/get`, `realtor/listings/search`, `seloger/listings/get`, `seloger/listings/search`.
- `site_unavailable` (503): Google did not answer in time or refused the call; retry later (not charged). From `google_maps/places/get`, `google_maps/places/search`, `google_maps/reviews/list`, `google_news/articles/search`, `lacentrale/listings/check`, `lacentrale/listings/get`, `lacentrale/listings/search`, `leboncoin/listings/check`, `leboncoin/listings/get`, `leboncoin/listings/search`, `leboncoin/phones/get`, `realtor/listings/get`, `realtor/listings/search`, `seloger/listings/get`, `seloger/listings/search`, `websites/contacts/get`, `x/profiles/get`, `x/tweets/list`, `x/tweets/search`.
