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",
      "reason": "unknown_field"
    }
  ]
}

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 - as does PATCH /api/v1/appointments/{id} whenever the edit moves the appointment. Each refusal is a 422 carrying the rule's own code, so you can tell them apart:

SLOT_NOT_OFFERED is the one to expect most, and it is not the same as SLOT_TAKEN: that one means somebody else has the time and another will do, this one means the business is shut. Ask GET /api/v1/availability/slots which start times it offers rather than guessing one.

If you are creating or moving 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 seventh 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.

Each entry has a path, a reason and a message

path is where the problem is, dotted into the request: customer.email, products[0].productId, or (body) / (query) / (path) when the request as a whole was rejected.

reason is what is wrong, as a stable identifier. Branch on this, not on message — the same rule as code at the top level. It is one of:

message is English written for a person reading a log. It may be reworded at any time and it never echoes what you sent, so treat it as a hint during development rather than as something to show a user or match on.

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",
      "reason": "unknown_field"
    }
  ]
}

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 carries the bound it crossed, in limit as well as in the message:

{
  "error": "Invalid request parameters",
  "code": "VALIDATION_ERROR",
  "fields": [
    { "path": "limit", "message": "Must be at most 100", "reason": "too_large", "limit": 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.