API error codes

No API key was sent with the request.

Cause

The Authorization header was absent, empty, or malformed. The most common version of this is sending the key as a bare string with no `Bearer ` prefix, or letting an empty environment variable interpolate into the header.

Fix

Send `Authorization: Bearer YOUR_API_KEY`. Check the variable actually resolved before the request went out — an unset env var produces a header that looks present and carries nothing.

The key was sent but does not match an active key.

Cause

The key was revoked, deleted, or belongs to a different account. Copy-paste truncation is the other frequent cause: keys are long enough that a partial selection still looks plausible.

Fix

Issue a fresh key from the dashboard and replace it in your environment. Keys are shown once at creation — if you cannot find it, mint a new one rather than guessing.

A parameter is missing, the wrong type, or out of range.

Cause

A required parameter was omitted, a limit exceeded the endpoint maximum, or a boolean arrived as something other than `true`/`false`. The `details` object names the offending parameter.

Fix

Read `error.details` — it names the field. Check the parameter against the endpoint reference, particularly the `limit` ceiling, which differs per source.

The path or the referenced record does not exist.

Cause

Either the endpoint path is wrong, or a job id, watch id, or lead id in the path belongs to another account or has been deleted.

Fix

Confirm the path against the source catalog at `/v1/sources`. For record lookups, confirm the id came back from this same API key — ids are scoped to the account that created them.

The balance cannot cover the hold for this run.

Cause

Credits are held against the limit you asked for, not the rows you end up with. Asking for 200 rows holds the cost of 200 rows even when the search only has 40 to give, so a balance that would cover the real result can still fail the hold.

Fix

Either top up, or lower `limit` so the hold fits the balance. The unused portion of a hold is returned automatically once the run settles, so a smaller limit is not a smaller result per credit.

The source refused or broke mid-run.

Cause

The underlying site rate-limited the collection, changed its markup, or returned nothing usable. Credits held for a failed run are refunded before the response is written, so a 502 never costs anything.

Fix

Retry with exponential backoff, starting at one second and doubling to a ceiling of thirty. Every response carries a request_id — quote it if you need to ask about a specific run. If the same query fails three times running, the source layout has probably changed — that is ours to fix, not yours.

The run outlived the synchronous request budget.

Cause

Large limits with enrichment turned on can exceed the window a synchronous HTTP request gets. This is a property of the request shape, not a fault.

Fix

Pass `async=true` and poll the job id instead. Any call you expect to return more than about a hundred enriched rows should be async from the start.

Something broke on our side.

Cause

An unhandled fault in the API layer. This one is always a bug, never a configuration problem.

Fix

Retry with exponential backoff, starting at one second and doubling to a ceiling of thirty. Every response carries a request_id — quote it if you need to ask about a specific run. If it persists, send the request_id to support — it resolves the exact run in our logs.