Errors

The problem details body every failure returns, how to read it, and every error code.

Every failed request returns an RFC 9457 problem details body with Content-Type: application/problem+json:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "this company needs its name and billing account before it can be invoiced",
  "code": "BOOKING_EXTERNAL_INVOICING_DETAILS_REQUIRED"
}

• status repeats the HTTP status.
• code names the rule that refused the request. Match on code, never on detail. A code never changes its meaning or its name.
• detail explains the failure to a person. Its wording can change.
• title is the HTTP status phrase.

A failure without a specific rule, such as a token without the right role, has no code.

Validation failures

A body, query or path parameter that does not match its schema returns 400 with code VALIDATION_FAILED. issues lists each field that failed, with its path and message:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed",
  "code": "VALIDATION_FAILED",
  "issues": [{ "code": "invalid_type", "path": ["fromDate"], "message": "Invalid input" }]
}

Status codes

The API host limits the requests from each IP address per minute: 600 under /v1/booking, 300 under /v1/billing and /v1/crm, and 60 under /v1/integrations. The identity host allows 60 a minute under /oauth. A request over a limit gets 429 from the gateway, and that body is not problem details.

The token endpoint uses its own error format. See Authentication.

Error codes

Validation

Booking

Billing

Signing

Integrations