Errors & conventions

This page covers the conventions that apply across the whole REST API: status codes, the response shape, and how updates (PATCH) work.

HTTP status codes

The API uses standard HTTP status codes. The exact codes per endpoint are in the reference; the common ones:

Status	Meaning	What to do
`200 OK`	Request succeeded	Read the body
`201 Created`	Resource created	Read the created resource / its id
`204 No Content`	Success, no body (e.g. delete)	Nothing to parse
`400 Bad Request`	Malformed request or invalid field	Fix the request; do not retry unchanged
`401 Unauthorized`	Missing/expired access token	Log in again via `login-api-token` (or refresh)
`403 Forbidden`	Token lacks permission / wrong scope	Use a token with the right scope
`404 Not Found`	No such resource	Check the id / path
`409 Conflict`	State conflict (e.g. not patchable now)	Resolve state, then retry
`422 Unprocessable Entity`	Validation failed	Fix the offending fields
`429 Too Many Requests`	Rate limited	Back off and retry later
`5xx`	Server error	Retry with back-off

Retry only what is safe: retry 429 and 5xx with exponential back-off. Do not blindly retry 4xx (other than 429) — the request needs changing first.

Response envelope

Listing responses carry the records plus pagination metadata (the cursor used by pagination).
Single-resource responses return the resource object.
Errors return a body describing what went wrong. Always read the response body on a non-2xx status — it explains the failure.

Because field-level shapes are defined per endpoint, treat the interactive reference as the source of truth for exact property names, and code defensively against optional fields.

async function call(path, init) {
  const res = await fetch(`${BASE}${path}`, init);
  if (!res.ok) {
    // Read the body for the error detail before throwing.
    const detail = await res.text();
    throw new Error(`MendriX ${res.status} on ${path}: ${detail}`);
  }
  return res.status === 204 ? null : res.json();
}

Updates use merge-patch

Updates are performed with PATCH using merge-patch semantics:

Only the fields you send are changed. Omitted fields are left untouched.
To send a partial update, include just the properties you want to modify.

# Update only the client's phone number; everything else is untouched.
curl -X PATCH \
  "https://<your-client-name>.api.mendrix.cloud/api/client/clients/CLIENT_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+31 20 123 4567" }'

Idempotency & consistency

Reads are safe to repeat.
PATCH with the same body is naturally idempotent — re-sending it lands the same state.
For create-style operations, guard against duplicates on your side (track what you have already sent) since there is no global idempotency-key header.