Errors
The error envelope and every status code the API returns.
Errors come back as JSON with a single human-readable error field and the matching HTTP status code:
{ "error": "Provide at least one of phone, email." }Status codes
| Status | Meaning | Typical cause |
|---|---|---|
400 | Bad request | The body isn't valid JSON. |
401 | Unauthorized | Missing, malformed, revoked, or expired token. |
404 | Not found | No such lead in this org (GET/PATCH). |
422 | Unprocessable | Validation failed, ambiguous owner, or unknown profile keys. |
429 | Too many requests | You exceeded 120 requests/minute — see Rate limits. |
500 | Server error | Something went wrong our side. Retry with backoff. |
Validation errors (422)
A 422 means the request was well-formed but the data wasn't acceptable. The error message names the problem — for example:
Provide at least one of phone, email.Provide owner_user_id or owner_email, not both.- An unknown
profilekey, with the allowed keys listed.
Fix the body and retry; retrying an unchanged 422 will fail the same way.
Handling errors
Treat 4xx as your bug to fix (don't blindly retry) and 429/5xx as transient (retry with exponential backoff). Always read the error string — it's written to tell you the next step.