Getting started

Errors

Failures come back as JSON with the same two shapes everywhere: a message you can log, and — when a field was rejected — an errors object that names it.

Error payloads

A 422 names every field that failed and why, keyed by field name. Anything else that fails carries a single message.

{
  "message": "The given data was invalid.",
  "errors": {
    "alias": [
      "The alias has already been taken."
    ]
  }
}

Status codes

200

SuccessThe payload is in the response body.

401

UnauthenticatedThe bearer token is missing, malformed, or revoked. Check it with GET /test.

403

ForbiddenThe token is valid, but the workspace role does not allow the call.

422

Validation failedRead errors — each key is a field, each value the reasons it was rejected.

5xx

Server errorRetry with exponential backoff. For non-idempotent writes, reconcile state before retrying because the spec does not prove whether the first attempt was applied.

Handle 422 field-by-field. The errors object is keyed by request field, so you can map it straight onto form state instead of showing the raw message.

Retrying safely

Reads and deletes are idempotent — retry them freely. POST creates a new record every time, so retry it only when you know the first attempt never reached the API, or reconcile afterwards with a list call.