Errors

An error answers with its HTTP status and a JSON body:

{
  "statusCode": 400,
  "message": "DOMAIN_REQUIRED",
  "error": "Bad Request",
  "traceId": "4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f",
  "timestamp": "2026-11-03T09:41:12.000Z",
  "path": "/v1/find-email"
}

message is a code in capitals, such as DOMAIN_REQUIRED, or a sentence for some campaign and inbox errors, such as Campaign not found. When the body fails validation, it is a list of what is wrong.
traceId names this error in LeadVector’s logs: quote it when you contact support.
Some errors carry more fields: a credit error says how many credits were needed, and a rate limit says when to retry.

Common errors

Status	When
400	The request is missing something, or holds something invalid. The route’s reference lists its codes.
401	No API key, or an unknown one (Authentication).
403	Not enough credits, no plan in force (Credits), or a deactivated account.
404	The campaign, lead, mailbox or message isn’t yours, or doesn’t exist.
409	A lead already in the campaign, when duplicates are refused.
429	Too many calls (Rate limits).
500	Something failed on LeadVector’s side. The message is always `Internal server error`; try again, and quote the `traceId` if it persists.

A lookup that finds nothing is not an error: it answers 201 with message: "NO_RESULT_FOUND", and costs nothing. Its data is empty: [] for an email or mobile lookup, null for a reverse lookup or an enrichment.

Get started

Webhooks

Common errors

​Common errors

Common errors