| 400 | INVALID_IDEMPOTENCY_KEY | The Idempotency-Key header is longer than 200 characters or not plain ASCII. | Capture a lead |
| 400 | INVALID_JSON | The body is not valid JSON. | Any endpoint |
| 400 | INVALID_QUERY | A parameter is out of range, filter is not valid JSON, or a filter cannot apply (unknown field key, an operator the field does not take, a bad value, more than 10). details.filters lists the positions of those filters (0-based); nothing is listed rather than ignoring them. | List leads |
| 400 | KEY_IN_URL | A key, or a parameter such as api_key or token, is in the URL. Keys go only in the Authorization header; replace a key that has been in a URL. | Any endpoint |
| 401 | UNAUTHORIZED | The key is missing, wrong, revoked or expired. | Every endpoint |
| 403 | FORBIDDEN | The key lacks the scope, or the organization’s plan does not include it. | Every endpoint |
| 403 | HTTPS_REQUIRED | The request was made over plain HTTP. | Any endpoint |
| 404 | NOT_FOUND | No lead with this ID in the organization, or it is archived. No lead with this ID in the organization. | Get a lead, Update a lead, Add a note |
| 409 | DUPLICATE_LEAD | A lead with this phone number or email already exists; details.leadId is its ID when known. The new phone number or email belongs to another lead. | Create a lead, Update a lead |
| 409 | IDEMPOTENCY_IN_PROGRESS | A request with this Idempotency-Key is still being handled. Retry in a few seconds. Another request saved the same person at the same moment. Retry; it will find that lead. | Capture a lead |
| 413 | PAYLOAD_TOO_LARGE | The body is over 100 KB. | Any endpoint |
| 415 | UNSUPPORTED_MEDIA_TYPE | A body was sent without Content-Type: application/json. | Any endpoint |
| 422 | VALIDATION_FAILED | A field is missing or invalid; details.fields says which. A refused stage, pipeline, owner or source gives details.reason (for example STAGE_NOT_IN_PIPELINE) and details.field. A value is missing or invalid, a key in fields is not one of the organization’s active fields (details.validKeys lists them), or a field the organization requires for a new lead is missing. This Idempotency-Key was used within 24 hours for a different body. pipelineId is not one of the organization’s pipelines. A field is invalid, or a required field would be emptied; details.fields says which. A refused stage, pipeline, owner or source gives details.reason (for example STAGE_NOT_IN_PIPELINE) and details.field. Nothing is changed when a request is refused this way. | Create a lead, Capture a lead, Update a lead |
| 429 | RATE_LIMITED | More than 600 requests in an hour with this key, or 3000 with all of the organization’s keys together. Retry-After says how many seconds to wait. | Every endpoint |
| 500 | INTERNAL | Something failed on our side. Retry; if it persists, contact support quoting the X-Request-Id response header. | Every endpoint |
| 503 | NOT_READY | The organization has no stage for new leads, or no active user to own them. Retry after it is set up. | Capture a lead |