Getting Started

Errors

The API uses conventional HTTP status codes and returns a consistent error body so you can handle failures programmatically.

Error envelope

Errors share a predictable shape:

json

{
  "statusCode": 400,
  "error": "Bad Request",
  "code": "VALIDATION_ERROR",
  "message": "startTime must be a valid HH:mm value"
}

statusCode mirrors the HTTP status. error is the status text. code is a stable machine-readable identifier you should branch on. message is human-readable and may change.

Branch on code, log message

Always switch on the stable code field. The message is for humans and is not guaranteed to be stable across releases.

HTTP status codes

Status	Name	When you see it
200	OK	The request succeeded.
201	Created	A resource was created.
204	No Content	The request succeeded and there is no body (for example a cancellation).
400	Bad Request	The request was malformed or failed validation.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	The key lacks a required scope, the route is blocked for API keys, or the plan does not include this feature.
404	Not Found	The resource does not exist or is not visible to this key.
409	Conflict	The request conflicts with current state (for example a double booking or a reused idempotency key with a different body).
422	Unprocessable Entity	The request was understood but cannot be processed as-is (for example a slot that is no longer available).
429	Too Many Requests	Rate limit exceeded. See Rate Limits.
500	Internal Server Error	An unexpected error on our side. Safe to retry idempotent requests.
503	Service Unavailable	The API is temporarily unavailable. Retry with backoff.

Error codes

Common code values you may encounter:

Code	HTTP	Meaning
`VALIDATION_ERROR`	400	One or more fields failed validation. See the message for details.
`UNAUTHORIZED`	401	The API key is missing, malformed, expired, or revoked.
`MISSING_SCOPE`	403	The key does not hold the scope required for this route.
`PLAN_REQUIRED`	403	This feature requires a higher plan (for example PRO for API access, ENTERPRISE for webhooks).
`FORBIDDEN_FOR_API_KEY`	403	This route can never be called with an API key (financial or destructive operation).
`NOT_FOUND`	404	The requested resource does not exist or belongs to another business.
`BOOKING_CONFLICT`	409	The requested time slot overlaps an existing booking.
`IDEMPOTENCY_KEY_REUSED`	409	The Idempotency-Key was reused with a different request body.
`SLOT_UNAVAILABLE`	422	The selected slot is no longer available.
`OUT_OF_SERVICE_AREA`	422	The address falls outside the business service area (for mobile or travel bookings).
`RATE_LIMITED`	429	Too many requests. Honor the Retry-After header.

Validation errors

Validation failures return 400 with a list of field-level messages:

json

{
  "statusCode": 400,
  "error": "Bad Request",
  "code": "VALIDATION_ERROR",
  "message": [
    "serviceIds should not be empty",
    "date must be a valid ISO 8601 date string"
  ]
}

For 429 handling, see Rate Limits.