Errors and limits

Errors

Errors use the JSON:API format: an errors array, each with a status, a title and a detail.

{
  "errors": [
    {
      "status": "422",
      "title": "Validation Error",
      "detail": "The contact.external_id field is required when none of contact.phone / contact.email are present.",
      "source": { "pointer": "/data/attributes/contact.external_id" }
    }
  ]
}

Validation errors include a source.pointer naming the field. A request can return several errors at once.

Status codes

Status	Meaning
200	OK. For POST /events, the event was already recorded with this Idempotency-Key.
201	Created.
202	Accepted: the event is recorded and automations start in the background.
204	Deleted.
401	No API key, or it’s invalid or deleted.
403	The key lacks the permission for this request, or your plan doesn’t include the API.
404	Not found, or not in this workspace.
422	The request isn’t valid; see errors. Also returned when a request would go over a plan limit, such as stored contacts.
429	Too many requests; see rate limits.
5xx	Something went wrong on our side. Retry with backoff.

Rate limits

	Limit
Each API key	120 requests a minute
Each workspace, across all its keys	600 requests a minute
POST /api/v1/events	1,200 requests a minute per workspace, counted separately

Every response says where you stand on the limit that applies to it (your key’s, or the events limit):

Header	Meaning
X-RateLimit-Limit	Requests allowed a minute.
X-RateLimit-Remaining	Requests left this minute.

Over a limit, requests get 429 Too Many Requests with a Retry-After header: wait that many seconds and try again. Creating more keys doesn’t raise the workspace limit. Give each system its own key so one busy integration can’t use up another’s allowance.

Retrying safely

Retry 429 and 5xx responses with increasing delays. Retrying POST /events is always safe when you send an Idempotency-Key.