Errors and limits

Problem JSON

Every refusal is application/problem+json:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "code": "bad_request",
  "detail": "`attributes.plan` should be a string, not a number",
  "request_id": "01JA...",
  "errors": [{ "field": "attributes.plan", "message": "should be a string, not a number" }]
}

Switch on code, never on detail: detail is a sentence for people and may be reworded. Quote request_id when asking for help. A 400 names the field that is wrong in errors, such as attributes.plan, events.2.name or external_id, and suggests the right name for a field it does not know.

Codes

Status	Code	What to do
400	bad_request	Fix the request: the problem names the field.
400	app_key_required	Send X-CRM-App-Key.
401	unauthorized	The key or token is wrong, revoked or for another app; the detail says which. Asking again will not help.
401	token_expired	Get a fresh token from your backend, and ask once more.
403	app_unavailable	The app is archived or deleted. Stop sending until it is restored.
404	not_found	Not there, or the part is switched off for the app.
409	erased	The person was erased lately: nothing new is kept about them.
409	refused	Not possible as things stand: the detail says why.
409	rating_closed, survey_closed, bot_moved_on	That moment has passed: read the conversation or survey again.
413		The body is too large.
422	attachment_invalid, answer_invalid	A picture or an answer that is not right.
429	rate_limited	Too many requests: wait for Retry-After seconds.
503	unavailable	Not set up yet, or briefly down. Try again later.

Limits

What	Limit
Server API, per key	1,200 requests a minute.
Server API events	500 a request.
Event definitions	500 a request; 250 events of your own an app.
Server keys	20 an app.
Guest API, per user	30 event batches and 120 other requests a minute.
Guest events	50 a batch.
Public routes, per address	About 120 requests a minute.
Webhook endpoints	20 an app.
New attributes and events on first sight	50 a day an app.
Identity tokens	At most 30 days long.

Past a limit, the answer is 429 with Retry-After. Spread a backfill over time so your live traffic keeps room.