Errors

The REST API uses standard HTTP status codes. A 2xx means success; a 4xx means the request was rejected; a 5xx means something failed on our side.

Error response shape

Every error returns the same JSON body:

{
  "success": false,
  "error": "Event not found"
}

The error string is a human-readable description of what went wrong. Successful responses do not include the success field — they return the resource directly. Write endpoints add detail where it helps you fix the request. A rejected PATCH lists every problem at once rather than the first:

{
  "message": "Some fields could not be accepted.",
  "errors": [
    "numPeople: must be a number of 0 or more.",
    "decisionFactors: 'Vibes' is not a recognized value. Valid: …"
  ]
}

A conflict that would drop agenda sessions names them in orphanedSessions — see Writing events.

Status codes

Status	Meaning	When
`400`	Bad Request	A path or query parameter is malformed (e.g. an event `id` that isn’t a valid UUID), or a write was rejected. Nothing is written on a `400`.
`401`	Unauthorized	The `x-api-key` header is missing or invalid. See Authentication.
`403`	Forbidden	The key’s user does not belong to the organization the write targets.
`404`	Not Found	The resource doesn’t exist or isn’t accessible to your key’s user — the two are indistinguishable, so you never learn whether another organization’s data exists.
`409`	Conflict	The event is cancelled, or the change would drop agenda sessions. Nothing is written. See Writing events.
`429`	Too Many Requests	You’ve exceeded the rate limit. See Rate limits.
`500`	Internal Server Error	An unexpected error on our side. Retry; if it persists, contact us.

A 404 is returned for both missing and inaccessible resources by design. Don’t treat it as proof that an id is invalid — only that it isn’t readable with your key.Every 4xx on a write means nothing was written, so it is always safe to correct the request and retry without first checking what partially landed.

Getting started

Events

Reference

Error response shape

Status codes

​Error response shape

​Status codes

Error response shape

Status codes