Errors

Every error response has the same shape:

{
  "error": {
    "code": "validation_error",
    "message": "name and company are required"
  }
}

code is machine-readable and stable. Branch on the code, never on the message.
message is a human-readable explanation. Its wording may change.
A 429 also carries retryAfterSeconds (see Rate limits).

Codes

HTTP	`code`	Meaning
400	`validation_error`	The request body, query or a header is invalid. The message names the first problem.
400	`invalid_continuation`	A lead-search `continueFromRunId` names no finished search of this workspace.
401	`unauthenticated`	The API key is missing, invalid or expired.
403	`forbidden`	The caller may not perform this action.
404	`not_found`	No such resource for this workspace, or the capability is not enabled on this deployment.
405	`method_not_allowed`	Wrong HTTP method. The `Allow` header lists the right one.
409	`idempotency_conflict`	The `Idempotency-Key` was already used for a different request. Send a new key.
409	`idempotency_in_progress`	The first request with this key is still running. Retry once it finishes.
409	`run_already_active`	A lead-search run is already active for this workspace.
429	`rate_limited`	The workspace’s request budget is spent. Retry after `Retry-After`.
500	`internal_error`	An unexpected failure on our side. Never billed.
503	`search_unavailable`	Lead search is not available right now. Never billed.

Each operation in the API reference lists exactly which of these it can return.

Outcomes that are not errors

A lookup that ran but found nothing is not an error. Lookups answer 200 with found: false and a reason (for example profile-not-found or insufficient-credits), so you can tell “nobody matched” from “the call failed”. A few operations answer such an outcome with its own status (the company lookup answers 402, 422 or 503 with the usual data body); the reference states which. Every lookup response says what the call consumed in charged and pointsCharged.

Get started

Using the API

Codes

Outcomes that are not errors

​Codes

​Outcomes that are not errors

Codes

Outcomes that are not errors