Errors and rate limits

When a request fails, the API answers with a non-2xx status and a JSON body holding one human-readable message:

{ "error": "API key is missing required scope(s): bookings:read" }

Branch on the status code. The messages are written for people and may get clearer over time, so log them and show them, but don't match on their exact text.

Status codes

Authentication errors

Every endpoint can return these.

Endpoint errors

A 500 carries a short message such as Failed to fetch bookings or Failed to update booking.

In the SDK

@clndr-pro/sdk throws a ClndrError for any non-2xx response. It carries the message, the status and the parsed body:

import { Clndr, ClndrError } from '@clndr-pro/sdk';
 
const clndr = new Clndr(process.env.CLNDR_SECRET_KEY!);
 
try {
  await clndr.bookings.create(input);
} catch (err) {
  if (err instanceof ClndrError && err.status === 409) {
    // Someone else took the slot: refetch slots and let the guest pick again.
  } else {
    throw err;
  }
}

err.status is the HTTP status, err.message is the API's error, and err.data is the whole response body. Network failures (DNS, timeouts) aren't wrapped: they reject with whatever fetch threw. The React hooks expose the same error object as error.

Rate limits

Each key gets a fixed 60-second window:

The count is per key, not per visitor: every guest on your site shares your publishable key's 120 requests a minute. A booking flow costs about one request per date the guest looks at, plus two (page and booking), so this covers a busy site. If you outgrow it, move slot lookups to your server and cache them for a minute.

A 429 comes with these headers:

Successful responses don't include them, so you can't watch your remaining budget; back off when you get a 429.

Two other limits apply to bookings specifically: one guest email address gets five booking attempts per clock hour, counting attempts that then fail (a 429 without Retry-After; it resets at the top of the hour), and each account can create five API keys an hour in the dashboard.

Retrying

GET requests are safe to retry. So are PATCH and DELETE on a booking, with two details: a PATCH without reason clears any cancellation_reason already stored, so resend the same reason; and PATCH doesn't check the current status, so confirming retries are safe but a stale "confirm" after the host declined confirms the booking again.

POST /bookings isn't. If a create times out, the booking may exist. Retrying the same slot then fails with a 409, which might be your own first attempt. From a server, look for the booking (clndr.bookings.list({ status: 'confirmed' }) or 'pending', matching guest_email and start_time) before telling the guest anything. In the browser, show the guest a neutral message and refetch the slots.

A small wrapper that honours Retry-After on idempotent requests:

const BASE = 'https://www.clndr.pro/api/v1';
 
export async function clndrGet<T>(path: string, key: string, attempts = 3): Promise<T> {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(BASE + path, { headers: { Authorization: `Bearer ${key}` } });
    if (res.ok) return (await res.json()) as T;
 
    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || attempt === attempts) {
      const body = await res.json().catch(() => ({}));
      throw new Error(`${res.status} ${body.error ?? res.statusText}`);
    }
 
    const wait = Number(res.headers.get('Retry-After')) || 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
}