Errors

Every error has an HTTP status, a stable code to branch on, and a message to show.

JSON

{
  "error": "Validation failed",
  "code": "bad_request",
  "details": ["urlPattern: Enter a URL pattern", "steps.2.title: Required"]
}

Field	Meaning
`error`	A readable message. It can change; don't parse it.
`code`	A stable code to branch on.
`details`	Optional. One line per problem, for validation errors.

Some errors add fields, like retryAfter on 429 or usage on segment_in_use.

Common codes

Status	Code	What happened
400	`bad_request`	The request is malformed or didn't validate: invalid JSON, a bad id, a missing or wrong field. For validation errors, `details` says what to fix.
400	`validation_failed`	The same, from a few endpoints that validate later. `details` says what to fix.
401	`unauthorized`	No key, or the key is invalid or revoked.
402	`plan_limit`	Your plan's limit is reached: the number of live items of a type, or AI features outside the Pro plan. The response has a `message` and an `upgrade_url`.
403	`forbidden`	The key's owner doesn't have the permission this needs.
403	`self_approval`	You can't approve your own review request.
404	`not_found`	It doesn't exist, or it's in another workspace.
409	`conflict`	It clashes with the current state, for example a duplicate.
409	`approval_required`	The workspace requires review before publishing to production. Send a review request with `POST /{type}/{id}/publish-requests`.
409	`segment_name_taken`, `segment_in_use`	A segment name is used, or the segment is still targeted by content.
413	`payload_too_large`	The body is too big.
415	`unsupported_media_type`	Send the body as `application/json`.
429	`rate_limited`	Too many requests. Wait for `Retry-After` seconds. See Rate limits.
500	`internal`	Something went wrong on our side. Retry later.
503	`unavailable` (and similar)	A service this needs isn't available right now.

Branch on code, not on error.
Retry 429 after Retry-After, and 500/503 with backoff. Don't retry other 4xx: fix the request.
PATCH requests send the whole list when you change steps, items or questions: read the item first, then send every entry back (keeping their ids).