Errors

Every error, on every endpoint, has the same shape:

{
  "error": "Invalid request parameters",
  "code": "VALIDATION_ERROR",
  "fields": [
    { "path": "statuss", "message": "Not a supported parameter for this endpoint" }
  ]
}

error is a string, not an object. code sits beside it at the top level rather than inside it. That is worth reading twice, because the other arrangement is the more common convention and a client written against it will find undefined where it expected a code.

code is a stable identifier and is what your code branches on. error is a sentence written for a human reading a log: it may be reworded at any time, and it never echoes what you sent.

Three members appear only on the codes that carry them:

Statuses

Codes

The business's own booking rules

A business configures rules the widget enforces, and POST /api/v1/appointments enforces the same ones. Each refusal is a 422 carrying the rule's own code, so you can tell them apart:

If you are creating an appointment on the business's behalf rather than on a customer's, for example from their own back-office tool, send enforceBookingRules: false in the body and none of these apply. That flag exists because a receptionist taking a booking by phone is not subject to the rules the public widget is.

The rule set is extensible, so a sixth code can appear. When it does, the message field carries a readable sentence naming it.

Two behaviours worth knowing about

A cross-tenant id is a 404, never a 403

Passing an id that belongs to another business returns 404 NOT_FOUND, exactly as a nonexistent id would. It is deliberate: a 403 would confirm that the record exists somewhere, which is a membership oracle over other businesses' data. You cannot tell the two cases apart, and neither can anyone probing.

fields names parameters you did not send

Query parsing is strict. A parameter this endpoint does not accept is a 400 naming it, rather than being ignored:

{
  "error": "Invalid request parameters",
  "code": "VALIDATION_ERROR",
  "fields": [
    { "path": "statuss", "message": "Not a supported parameter for this endpoint" }
  ]
}

A typo in a filter that is silently dropped gives you a full unfiltered list and no signal, and that is a worse failure than a 400 during development. Request bodies behave the same way.

An out-of-range value reads the same way, with the bound in the message:

{
  "error": "Invalid request parameters",
  "code": "VALIDATION_ERROR",
  "fields": [{ "path": "limit", "message": "Must be at most 100" }]
}

Retrying safely

GET requests are safe to retry freely. Use exponential backoff and honour Retry-After on a 429.

Creating POST requests are safe to retry because they require an Idempotency-Key. Retry with the same key and you either get the original result or a clear conflict, never a duplicate appointment. Retrying with a new key on a request that may have succeeded is how you double-book somebody.

PATCH and the status transition are naturally idempotent: setting a status to cancelled twice is one cancellation.

When you need to see what happened

The business owner has a Logboek screen in the product listing every request made with their keys: method, path, status, error code, duration and timestamp. If your integration is failing and the error is not telling you enough, that log is the shared view of reality between you and them. Webhook deliveries have an equivalent log with the full payload and every retry attempt.