Errors

Format

All HTTP errors from the API use this envelope:

{
  "error": {
    "code": "not_authenticated",
    "message": "A valid API key is required."
  }
}

Field	Usage
`code`	Stable. Branch your logic on this.
`message`	For humans. May change. In English.
`details`	Optional. On `invalid_request`, and on `validation_error` when the schema refused the input: list of invalid fields. When `details` is absent, `message` says what to fix. On a `404` for a service name that does not exist: the object `{ "reason": "unknown_service" }`.

What `message` says

This section covers Services: a direct call on POST /services/{serviceName}, jobs[i].error in a batch, cells[key].error on a table row (/v1/tables, /v1/runs), and failed cells on a share link. Go is not covered yet. message is human text. Its words can change at any time. On a service call or a job line, do not parse it: branch on code. A table cell has no code. In cells[key].error you can rely on two things:

An http_NNN status, when the provider sent one. For example http_502: A data provider returned an error. Try again later.
The lead-in of a contact lookup. No answer yet: means the lookup has no verdict yet: run it again later. Lookup failed means the input was refused: fix it before you run it again.

message keeps the words of the error, so you can act on them: the field to fix, the value that was refused, the balance, the error of your own code in a code column, and the short reason a provider gave in words. For example http_400: invalid linkedin url. On provider_rejected, the reason comes in a sentence: http_400: A data provider refused this input: invalid linkedin url. Check the input values. These parts are removed:

A provider’s raw answer: an HTML page, or a JSON body (its short reason stays when it has one). A plain answer after a status is cut at 200 characters.
Keys, tokens and credentials (Bearer ..., Basic ..., api_key=..., password: ..., sk-..., credentials in a URL), long unbroken ids, and our internal addresses (database URLs, internal hosts, private IP addresses). Each one reads [redacted].
A stack trace, from its first frame.
A provider’s exact API host, and its pool or key ids (for example parallel-key-7). Each one reads provider.

When no words are left, or when the failure is our database’s own error, message is a fixed sentence led by the status, for example http_502: The service could not complete. Try again later. capacity and provider_unavailable use a fixed sentence, except contact lookups, which keep their lead-in.

Validation errors

On /v1/runs, /v1/tables, /v1/workspaces, and /v1/exclusions, an invalid body or query returns 400 invalid_request. message names each faulty field. details gives the same list in structured form:

{
  "error": {
    "code": "invalid_request",
    "message": "prompt: prompt must not be blank; columns[0].key: Too small: expected string to have >=1 characters",
    "details": [
      { "path": "prompt", "message": "prompt must not be blank" },
      { "path": "columns[0].key", "message": "Too small: expected string to have >=1 characters" }
    ]
  }
}

An unknown field has an empty path and the message Unrecognized key: "…".
Unreadable JSON returns Request body must be valid JSON.

On /v1/go/* and /services, an invalid body returns 400 validation_error with details. A field a service does not define, at any depth, is refused and named in message: it is never dropped silently, so a misspelled criterion cannot widen a search. On POST /v1/services/jobs/batch, one invalid input refuses the whole list with 400 invalid_request, and message names the input’s index. An input the schema accepts but that names too little to search (a contact with no LinkedIn profile, and no first and last name with a company) is not refused: that line alone ends provider_rejected.

{
  "error": {
    "code": "validation_error",
    "message": "query is required",
    "details": [{ "path": ["query"], "message": "query is required" }]
  }
}

Statuses and codes

HTTP	`code`	Cause	What to do
`400`	`invalid_request`	Unreadable JSON, unknown field or query parameter, wrong type, `limit` outside 1–1000, empty `Idempotency-Key`, invalid `output` contract.	Fix the fields named in `message` and `details`.
`400`	`validation_error`	Input rejected by Go or Services: the schema refused it, or a value cannot be searched (an unknown country or location, a malformed post URL, a cursor that was not returned by the API, a search with no filter).	Fix the fields listed in `details`, or what `message` says to fix when `details` is absent. Do not retry as is.
`400`	`invalid_cursor`	Cursor is from another table or run.	Restart reading without `cursor`.
`400`	`workspace_mismatch`	`conversation_id` does not belong to the given `workspace_id`.	Send only one of the two, or the correct pair.
`401`	`not_authenticated`	Missing or malformed `Authorization` header, or revoked key.	Check `Bearer ret_live_…` format. Create a new key if needed.
`402`	`insufficient_credits`, `usage_limit`	Insufficient balance (Go, Services). On `POST /v1/services/jobs/batch`, the balance cannot reserve one new line: no job is created.	Check `GET /credits`, top up, then retry.
`403`	`forbidden_origin`	A browser request authenticated by the session cookie, sent from a page that is not Retriever’s. API-key requests never get it.	Call the API with an API key (`Authorization: Bearer ret_live_…`).
`404`	`run_not_found`, `table_not_found`, `workspace_not_found`, `conversation_not_found`, `output_not_found`, `export_not_found`, `not_found`	Unknown, archived, or another organization’s resource. A Go job started by another user of your organization. A misspelled service name on `POST /v1/services/jobs/batch` too. On `POST /services/{serviceName}`, `not_found` also means the thing you asked for does not exist (a post, a company page): it is not retryable. A job line can also end `not_found` when what the input names does not exist: no job service returns it today; treat it as not retryable if it appears. An unknown service carries `details.reason: "unknown_service"`; a service’s own `not_found` has no `details`.	Verify the identifier and key in use. `GET /services` lists the services.
`409`	`idempotency_conflict`	Same `Idempotency-Key`, different body.	Client bug: generate a new key for a new request.
`409`	`conversation_busy`	A run is already active in this conversation (API or chat), including a run still `queued`.	Wait for the active run to finish. Or cancel it and wait until its status is final (`completed`, `failed` or `cancelled`: it may finish before the cancellation lands) before you send again. A run started in the app cannot be cancelled from the API.
`409`	`job_shared`	A cancel of a service job that another list of your organization also points to.	Nothing: the job keeps running for that list.
`413`	`body_too_large`	The request body is over 10 MiB (10,485,760 bytes), or over 25 MiB (26,214,400 bytes) on a table import. `/oauth/*` and `/mcp` use the next row.	Do not retry the same body. Check its size before sending, and send less data per request. See Rate limits.
`413`	On `/oauth/*`: OAuth form `{"error":"invalid_request","error_description":"..."}`, not the envelope above. On `/mcp`: a JSON-RPC error object with `error.code` `-32600` and `error.data.code` `body_too_large`.	The request body is too large: over 64 KiB on `/oauth/*`, over 10 MiB on `/mcp`.	Send a smaller body. On `/mcp`, send one JSON-RPC message per request.
`415`	`invalid_request`	Missing `Content-Type` or not `application/json`.	Add `Content-Type: application/json`.
`429`	`rate_limited`	Request budget exceeded.	Wait `Retry-After` seconds. See Rate limits.
`429`	`too_many_runs`	5 Go jobs (`POST /v1/go/runs`) already running for this user.	Wait for one to finish, or `Retry-After` seconds, then start it.
`500`	`internal_error`	Unexpected server error.	Retry with backoff: `GET`, `POST` with `Idempotency-Key`, or a Go job cancel.
`502`	`provider_error`, `upstream_error`, `agent_error` (Go), `capability_error` and `interrupted` (Services)	An external provider failed, or the call was cut off. Since 2026-10-02, a refused input no longer ends here: see Changed on 2026-10-02.	Retry with backoff. A retried `POST` runs again as a new call and is billed as one. A failed Services call costs nothing.
`502`	`invalid_output` (Services)	The service answered outside its own contract: a fault on our side.	Do not resend: the same request fails the same way until it is fixed. Tell us.
`422`	`provider_rejected` (Services)	This input was refused: the provider would not take it, or, for a contact lookup, it gives too little to search (give a LinkedIn profile, or a first and last name with the company). Unlike `provider_error`, the fault is in the input.	Do not retry as is: fix the input.
`503`	`capacity`, `provider_unavailable` (Services)	The provider had no room, or no provider account could be used. Nothing was charged.	Send the same request again a few minutes later.
`503`	`runs_unavailable`	Run storage unavailable (`/v1/runs`, `/v1/tables`).	Retry later.
`503`	`key_check_busy`	The key could not be checked right now, often a key just created, during a flood of unknown keys.	Retry after `Retry-After` seconds.
`503`	`server_restarting`	A Go job (`POST /v1/go/runs`) asked for while the server restarts. Nothing was started.	Send it again after `Retry-After` seconds.
`504`	`timeout` (Services)	The service used its time budget before the provider answered. It costs nothing, unless the provider’s answer lands just after the cut: the call is then billed as usual. The error carries no `credits`: such a charge shows only in the balance (see Reconciling with GET /credits).	Send the same request again a few minutes later.
`410`	`list_only`	A slow service called on `POST /services/{serviceName}`, or a job sent alone on `POST /v1/services/jobs` (any service).	Send it on `POST /v1/services/jobs/batch` (`details.batch_url`), even for one person.

Changed on 2026-10-02

These failures were sent as 502 capability_error, and as a job line capability_error with retryable: true. They are now sent as 400 validation_error or 404 not_found, with retryable: false: sending the same input again gets the same answer.

Case	Services	Before	Now
A cursor that the API did not return	The 11 list services with a cursor (`growthCompanies`, `peopleByRole`, `jobPostings`, …)	`502 capability_error`	`400 validation_error`
An unknown country	Services that search people or companies by country	`502 capability_error`	`400 validation_error`
An unknown or ambiguous location or language, similar mode without a seed	`searchCreators`	`502 capability_error`	`400 validation_error`
A post URL or URN that cannot be read as a LinkedIn post URL or URN, an invalid `postedAfter`	LinkedIn post, post comment and company post services	`502 capability_error`	`400 validation_error`
`hybrid: false` that excludes every workplace type	TheirStack job search services	`502 capability_error`	`400 validation_error`
A profile that is not a URN, a URL or an alias, or whose URN cannot be read from its posts (it may have none): send `urn:li:fsd_profile:...`	`getLinkedInUserComments`, `getLinkedInUserReactions` (list only: a direct call gets `410 list_only`)	job line `capability_error`, `retryable: true`	job line `validation_error`, `retryable: false`
A Reddit post or a LinkedIn company that does not exist	`getRedditPost`, `getLinkedInCompanyPosts`	`502 capability_error`	`404 not_found`

A line of a batch that ends failed is never a found: false. Its failed attempt costs nothing, except the Deep agent’s miss price when a contact lookup’s Deep agent finished its search. A call cut by a timeout can still be billed if the provider’s answer lands just after the cut. A line that ends worker_lost can also be billed: its call may have run, and been paid, before the worker was lost. The line’s credits.charged gives what it really cost, earlier attempts included. It can grow after the line ends when a charge is recorded late, most often for a call cut by a timeout whose answer landed just after the cut. Late charges usually land within seconds, but this is not guaranteed: read it again a few minutes after the end. This table is the reference for every service surface. error.retryable says whether the same input can get an answer later. “Send it again” always means a new line: a failed line is never handed out as an answer, and the new line is billed like any lookup.

`error.code`	`retryable`	Cause	What to do
`capacity`	`true`	The provider had no room.	Send that input again in a new batch a few minutes later.
`timeout`	`true`	The provider did not answer in time, or the job used its time.	Same. If the provider answered after the cut, the new line can get that answer without a new provider search.
`interrupted`	`true`	The search was cut off before it ended.	Same.
`provider_error`	`true`	The provider failed on its side, or refused the whole request it was sent. The input is not at fault.	Same.
`capability_error`, `service_error`, `service_execution_failed`	`true`	The service failed without saying why (a provider’s 5xx, a network cut): mostly transient. A value the service cannot search ends `validation_error` or `not_found` instead.	Same. If the same input keeps failing this way, check it.
`provider_unavailable`	`true`	A provider or its account could not be used (no enabled account, key refused, credits out at the provider).	Same.
`worker_lost`	`true`	A restart on our side, twice, after the call started.	Same.
`usage_limit`	`true`	The balance ran out while the batch ran.	Top up, then send the failed inputs again.
`provider_rejected`	`false`	This input was refused: the provider could not search it (an invalid domain, a malformed profile), or, for a contact lookup, it gives too little to search, or too little for the databases chosen in `databases`. The other lines are unaffected.	Do not send it again as is. Give a LinkedIn profile, or a first and last name with the company; `company_domain` must be a domain like `acme.com` or an email address (a web page there is ignored, so give `company_name`). With `databases`, give what each needs (`fiber`: a LinkedIn profile; `hunter`: a name and the company domain), or choose another.
`validation_error`	`false`	The service refused the input (an unknown country or location, a malformed URL, a search with no filter).	Fix the input: `message` says what to fix.
`not_found`	`false`	What the input names does not exist. No job service returns it today; treat it as not retryable if it appears.	Do not send it again as is.
`invalid_output`	`false`	The service answered outside its own contract, a fault on our side.	The same input fails the same way until it is fixed: tell us.

A found: false means every planned step finished, the Deep agent and the email verification included, and none gave an answer. One exception: a getPhoneNumber backup database (fiber or lusha, wherever it runs; never fullenrich) that could not answer (down, out of credits, rate limited, timed out, refused the call, not set up, or no time left in the lookup) is skipped, its attempt in waterfall reads category: "skipped", and the lookup still ends found: false without charge for the databases. That answer does not settle the skipped database: the same person sent again runs it again, unless databases leaves it out. getEmail’s hunter skipped ahead of fullenrich runs again after fullenrich when fullenrich did not find the email, and the line fails as unresolved if it fails again (a hunter that refuses this person counts as done). When none of the databases in databases could look (each skipped, or none can read this person, such as fiber without a LinkedIn profile or hunter without a name and company domain), the line fails instead with strategy: providers: provider_rejected when none can read this person, else provider_unavailable (a fiber or lusha that refused this person reads provider_unavailable too: with that database alone, choose another). When the Deep agent is in the strategy, its search stands: found: false at its miss price. With verifyEmail: true, a candidate the verification rejected also ends found: false: email is null, the rejected address is not returned, and verification says why. A lookup where one of those steps broke ends failed as unresolved instead.

Job failure vs HTTP error

A failed run or Go job remains a readable resource with 200. Read status and error:

{ "id": "run_001", "status": "failed", "error": { "code": "agent_execution_failed", "message": "…" } }

Possible run.error.code values: agent_execution_failed, run_timeout (run exceeded maximum duration, 3 hours by default, counted from its start: time spent queued does not count), run_lease_lost, run_access_revoked, agent_ followed by a status. For internal codes, message may match code. For which errors to retry, see Make your integrations robust.

Get started

Model Context Protocol

Concepts

Recipes

Format

What `message` says

Validation errors

Statuses and codes

Changed on 2026-10-02

Job failure vs HTTP error

​Format

​What message says

​Validation errors

​Statuses and codes

​Changed on 2026-10-02

​Job failure vs HTTP error

Format

What `message` says

Validation errors

Statuses and codes

Changed on 2026-10-02

Job failure vs HTTP error