Errors

A failed request returns a non-2xx status and the same body shape every time:


{
  "error": {
    "code": "invalid_request",
    "message": "linkedin_url: Provide linkedin_url, or first_name + last_name + domain (or organization_name)"
  }
}

Branch on error.code — it is stable. error.message is written for a human and may change wording.

A lookup that finds nothing is not an error. It is a 200 with "status": "not_found" and "data": null, and it is free.

Error codes

Status	`code`	Charged	Meaning	What to do
400	`invalid_request`	No	The body failed validation, was not valid JSON, or a header was malformed. The message names the field.	Fix the request. Do not retry unchanged.
401	`invalid_api_key`	No	The `Authorization` header is missing, or the key is unknown, revoked or inactive.	Check the key in Settings → API keys.
402	`insufficient_credits`	No	The organization does not have enough credits for this lookup.	Top up or upgrade on usage and billing, then retry.
404	`invalid_request`	No	The path or method does not exist.	Check the URL — every endpoint is a `POST` under `/v1/api/enrich/`.
409	`idempotency_conflict`	No	The `Idempotency-Key` was already used with a different body, or a request with that key is still running.	Use a new key for a new request, or wait and retry the same one.
413	`invalid_request`	No	The request body is too large.	Send one lookup per request.
429	`rate_limited`	No	More than 60 requests in a minute on this key.	Back off and retry. See rate limits.
500	`internal_error`	No	Something failed on our side.	Retry with backoff, using the same `Idempotency-Key`.
504	`timeout`	No	The lookup ran past the server deadline. Any credits held for it are refunded.	Retry with backoff.

Validation messages

400 messages name the field and the rule, joined with ; when several fail:

Request	Message
`work-email` with no identifiers	`linkedin_url: Provide linkedin_url, or first_name + last_name + domain (or organization_name)`
`personal-email` or `mobile` with no URL	`linkedin_url: Required`
`verify-email` with a malformed address	`email: Invalid email format`
A field over its length cap	`domain: Domain must be at most 256 characters`
An empty or oversize idempotency key	`Idempotency-Key must be 1-255 characters`

String fields are trimmed before validation, so " jane@stripe.com " is accepted as jane@stripe.com.

Retrying safely

Retry?	Statuses
Yes, with backoff	`429`, `500`, `504`
Yes, after fixing the account	`402`
No — fix the request	`400`, `401`, `404`, `413`
Wait, then retry the same request	`409` with “still in progress”

Always retry with the same Idempotency-Key you sent the first time. If the original request actually succeeded, you get its response back instead of a second charge. See Rate limits and retries.