Errors

How the Bridge API reports errors, what each error code means and what to do about it.

When a request fails, the response has an HTTP error status and a body with status: "error":

{
  "status": "error",
  "error": {
    "code": "forbidden",
    "message": "This API key is read-only. Create a key with write access to make changes."
  }
}

code is stable, so use it in your code to decide what to do.
message explains the problem in plain language. It can change, so show it to people or log it rather than matching on it.

When a request field is invalid, the message starts with the field name, for example take: Number must be less than or equal to 100 or attendee.email: must be a valid email.

Error codes

Status	Code	What it means	What to do
`400`	`validation_error`	A field is missing or invalid, or the request can't be completed as sent (for example the booking page isn't accepting bookings).	Fix the request using the message. Don't retry it unchanged.
`401`	`unauthorized`	The API key is missing, invalid or revoked.	Check the `Authorization` header and that the key is still listed in Settings → API keys.
`403`	`forbidden`	The key can't do this: it's read only, its owner doesn't have permission for this item, its creator is no longer an owner, or the plan doesn't include the API.	Use a key with the right access, or change the request.
`404`	`not_found`	The item doesn't exist in this workspace, or the key can't see it.	Check the ID.
`409`	`conflict`	The change conflicts with existing data: the time was just booked by someone else, or a booking page URL is already taken.	Get fresh open times from `GET /slots` and pick another, or change the conflicting value.
`429`	`rate_limited`	Too many requests.	Wait and retry. See Rate limits and pagination.
`500`	`internal_error`	Something went wrong on Bridge's side.	Retry after a short wait. If it keeps happening, contact us.
`502`	`upstream_error`	A service Bridge depends on didn't respond.	Retry after a short wait.
`503`	`unavailable`	The feature isn't available right now.	Retry later.

Retrying safely

Retry 429 and 5xx errors with a growing delay between attempts. Before retrying a POST /bookings that timed out, check GET /bookings for the booking first, so you don't book the same meeting twice.

Was this page helpful?