Errors

Status	When
200 OK	The idempotencyKey was already used; returns the first lead.
201 Created	The lead was received.
400 Bad Request	The body is invalid. Fix the request before retrying.
401 Unauthorized	The API key is missing, invalid or revoked.
429 Too Many Requests	The key went over 300 requests per minute. Retry after a minute.
5xx	Something failed on our side. Retry with the same idempotencyKey.

Validation errors

A 400 lists every problem, with the field’s path and an error code:

{
  "message": "Validation failed",
  "issues": [
    { "path": "email", "message": "validation.invalidEmail" },
    { "path": "sourceId", "message": "validation.invalidReference" }
  ]
}

Code	Meaning
validation.leadContactRequired	Neither email nor phone was sent. Reported on email.
validation.invalidEmail	email isn’t a valid address.
validation.invalidPhone	phone isn’t 6–32 digits, spaces or + ( ) - .
validation.invalidId	An ID field isn’t a UUID.
validation.invalidReference	sourceId or campaignId doesn’t exist in your organization.
validation.tooLong	A text field is over its maximum length.

Fields without a code of their own, like an unknown channel, return a plain-English message instead.

Other errors

401 and 429 return a message:

{ "statusCode": 401, "message": "Invalid API key", "error": "Unauthorized" }