Rate limits & errors

Rate limits

Rate limits are enforced per API key. When you exceed a limit, the API returns 429 with a Retry-After header telling you how many seconds to wait.

Limit	Applies to
120 requests / minute	Every request, per key.
600 requests / hour	Additional cap on `POST /contacts`.

Rate limit headers

Every response carries the current window state, and 429 responses add Retry-After.

Header	Meaning
`RateLimit-Limit`	Requests allowed in the window.
`RateLimit-Remaining`	Requests left in the current window.
`RateLimit-Reset`	Seconds until the window resets.
`Retry-After`	Seconds to wait before retrying (on 429).

Retry guidance

Retry 429 and 5xxresponses with exponential backoff. On a 429, honor Retry-After as the minimum wait. Do not retry 4xx responses other than 429, because the request itself needs to change first.

Add jitter to your backoff so retries from many clients do not align into bursts, and cap the total number of attempts.

Error envelope

All errors share one JSON shape. statusCode, error, and message are always present. code is a stable machine-readable string, and fieldName appears on validation errors to name the offending field.

json

{
  "success": false,
  "statusCode": 422,
  "error": "Validation",
  "code": "ERR_FORM_VALIDATION",
  "message": "contactTypeId is required.",
  "fieldName": "contactTypeId"
}

Status codes

Status	When it happens
`401`	Missing, malformed, unknown, revoked, or expired API key. The message is opaque.
`403`	The key is valid but lacks the required scope.
`404`	The resource does not exist in this project.
`409`	A uniqueness constraint was violated (for example, a contactId already in use).
`422`	The request body or query failed validation; see fieldName.
`402`	The project contact quota is exhausted.
`429`	Too many requests; retry after Retry-After.
`500`	An unexpected server error; retry with backoff.