Errors

HTTP status codes

Request-level errors

When the whole request is rejected (before any rows are processed), the response body is:

{ "error": "<message>" }

Examples:

{ "error": "contacts must not be empty." }

{ "error": "Max 1000 contacts per request." }

These are returned with a 400 status.

Per-row validation errors (207)

A row that fails validation does not abort the batch. The failed row is skipped and reported in results with "status": "error" and a human-readable error string:

{
  "created": 2,
  "updated": 0,
  "errors": 1,
  "results": [
    { "index": 0, "status": "created", "id": "cmq2abc2def3ghi4jkl5" },
    { "index": 1, "status": "updated", "id": "cmq7mno7pqr8stu9vwx0" },
    {
      "index": 2,
      "status": "error",
      "error": "name: Required"
    }
  ]
}

The error string format is field: message for each failing validation, joined by ; . Field names match the Contact object reference.

An unresolved companyExternalId produces a dedicated error and no contact is created for that row:

{ "error": "companyExternalId: no company found for \"NOPE\"." }

Limits

• Max 1,000 contacts per request — enforced at the request level (400 if exceeded).
• Each API key is limited to 120 requests/minute (platform-enforced). Exceeding it returns 429 Too Many Requests with a Retry-After header (seconds until the window resets).
• Keep request payloads reasonable in size; a body-size cap is also on the roadmap.