Skip to content
Kwickblocks Developers

Errors

Every error from the Booking API is an RFC 9457 problem details body with the content type application/problem+json:

{
  "type": "https://developers.kwickblocks.ai/problems/booking-not-found",
  "title": "Booking not found",
  "status": 404,
  "detail": "I couldn't find a booking with that reference and phone number.",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}
  • type identifies the problem and links to its page below. Branch on type, not on title or detail.
  • detail is written to be safe to read to a guest as it is, and never contains anything about other guests.
  • traceId identifies the request. Quote it to the venue group when you report a problem.

429 answers carry a Retry-After header in seconds.

Over MCP, an error arrives as a tool error whose text is the same problem JSON.

Problem types

Section titled “Problem types”
Status Type Meaning
400 validation-failed A field is missing or not valid.
400 venue-required The key covers several venues; send venueId.
400 idempotency-key-required A POST without an Idempotency-Key header.
401 invalid-key The key is missing, unknown, revoked or expired.
403 capability-missing The key doesn’t have the capability this needs.
404 not-found The thing asked for doesn’t exist, or isn’t available to this key.
404 venue-not-found The venue doesn’t exist or the key doesn’t cover it.
404 booking-not-found No booking with that reference and phone number.
404 knowledge-not-found The venue hasn’t published that information.
409 no-availability The time has just gone.
409 booking-not-changeable The booking can’t be changed any more.
409 no-deposit-due There is no deposit to pay.
409 deposit-link-unavailable The venue can’t text payment links yet.
409 idempotency-conflict The Idempotency-Key was used for a different request.
409 conflict Someone else changed it first; try again.
429 rate-limited Too many requests from this key.
429 lookup-throttled Too many failed booking lookups.
429 too-many-links The deposit link has been texted too often this hour.
500 server-error Something went wrong on our side.
503 service-unavailable The information is briefly unavailable.