---
title: Errors
description: The problem details body every failure returns, how to read it, and every error code.
---

Every failed request returns an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details body with `Content-Type: application/problem+json`:

```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`:

```json
{
  "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

| Status | Meaning | What to do |
| --- | --- | --- |
| `400` | The request is not valid, or the current state does not allow it. | Read `code`. Fix the request or wait for the state to change. |
| `401` | The token is missing, expired or not valid. | Get a new token and retry once. |
| `403` | The token does not allow this request. | Check the token's roles. Do not retry. |
| `404` | The resource does not exist, or the token cannot see it. | Do not retry. |
| `409` | The request conflicts with the resource's current state. | Read the resource again before you decide. |
| `429` | Too many requests. | Wait and retry with backoff. |
| `5xx` | Hydda One failed. | Retry with backoff. |

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](/guides/authentication#token-endpoint-errors).

## Error codes

### Validation

| Code | HTTP status | Meaning |
| --- | --- | --- |
| `VALIDATION_FAILED` | 400 | The request is not valid. |

### Booking

| Code | HTTP status | Meaning |
| --- | --- | --- |
| `BOOKING_SLOT_TAKEN` | 409 | It conflicts with something that already exists. |
| `BOOKING_NO_COVERING_CONTRACT` | 400 | The current state does not allow it. |
| `BOOKING_CONTRACT_ATTRIBUTION_AMBIGUOUS` | 400 | The current state does not allow it. |
| `BOOKING_CONTRACT_NOT_A_CANDIDATE` | 400 | The current state does not allow it. |
| `BOOKING_NO_SHARED_CONTRACT` | 400 | The current state does not allow it. |
| `BOOKING_EXTERNAL_CONTRACT_NOT_BILLABLE` | 400 | The current state does not allow it. |
| `BOOKING_EXTERNAL_CUSTOMER_NOT_FOUND` | 404 | It does not exist, or the token cannot see it. |
| `BOOKING_EXTERNAL_CUSTOMER_BILLING_ACCOUNT_REQUIRED` | 400 | The current state does not allow it. |
| `BOOKING_EXTERNAL_BILLING_ACCOUNT_INCOMPLETE` | 400 | The request is not valid. |
| `BOOKING_EXTERNAL_INVOICING_DETAILS_REQUIRED` | 400 | The request is not valid. |
| `BOOKING_EXTERNAL_REQUIRES_APPROVAL` | 400 | The request is not valid. |
| `BOOKING_REQUEST_ID_ALREADY_USED` | 409 | It conflicts with something that already exists. |
| `BOOKING_GUEST_LINK_INVALID` | 404 | It does not exist, or the token cannot see it. |
| `BOOKING_GUEST_LINK_NOT_RESENDABLE` | 400 | The current state does not allow it. |
| `BOOKING_NOT_EXTERNAL` | 400 | The current state does not allow it. |
| `BOOKING_PRICE_RULE_AMBIGUOUS` | 400 | The current state does not allow it. |
| `BOOKING_PRICE_RULE_NOT_APPLICABLE` | 400 | The current state does not allow it. |
| `BOOKING_NOT_PENDING_APPROVAL` | 400 | The current state does not allow it. |
| `BOOKING_APPROVAL_WINDOW_PASSED` | 400 | The current state does not allow it. |
| `BOOKING_RESOURCE_IMAGE_REJECTED` | 400 | The current state does not allow it. |
| `BOOKING_RESOURCE_PURCHASE_TERMS_REJECTED` | 400 | The current state does not allow it. |
| `BOOKING_OUTSIDE_OPEN_HOURS` | 400 | The current state does not allow it. |
| `BOOKING_DURATION_TOO_SHORT` | 400 | The current state does not allow it. |
| `BOOKING_DURATION_TOO_LONG` | 400 | The current state does not allow it. |
| `BOOKING_DURATION_NOT_ON_INCREMENT` | 400 | The current state does not allow it. |
| `BOOKING_START_NOT_ON_INCREMENT` | 400 | The current state does not allow it. |
| `BOOKING_WEEKLY_QUOTA_EXCEEDED` | 400 | The current state does not allow it. |
| `BOOKING_BUFFER_CONFLICT` | 409 | It conflicts with something that already exists. |
| `BOOKING_NOTICE_TOO_SHORT` | 400 | The current state does not allow it. |
| `BOOKING_CANCELLATION_NOTICE_EXPIRED` | 400 | The current state does not allow it. |
| `BOOKING_ALREADY_DELIVERED` | 400 | The current state does not allow it. |
| `BOOKING_NOT_CHARGED` | 400 | The current state does not allow it. |
| `BOOKING_ALREADY_STARTED` | 400 | The current state does not allow it. |
| `BOOKING_ACCESS_ALREADY_OPEN` | 400 | The current state does not allow it. |
| `BOOKING_NOT_RESCHEDULABLE` | 400 | The current state does not allow it. |
| `BOOKING_TIME_SPEC_MODEL_MISMATCH` | 400 | The current state does not allow it. |
| `BOOKING_SLOT_NOT_IN_SCHEDULE` | 400 | The current state does not allow it. |
| `BOOKING_DATE_INTERVAL_EMPTY` | 400 | The current state does not allow it. |
| `BOOKING_DATE_SPAN_EMPTY` | 400 | The current state does not allow it. |
| `BOOKING_DATE_SPAN_REQUIRES_SESSION_PRICING` | 400 | The current state does not allow it. |
| `BOOKING_DATE_INTERVAL_REQUIRES_NIGHT_PRICING` | 400 | The current state does not allow it. |
| `BOOKING_NIGHT_PRICING_REQUIRES_DATE_INTERVAL` | 400 | The current state does not allow it. |
| `BOOKING_RESOURCE_BUFFER_NOT_ON_INCREMENT` | 400 | The current state does not allow it. |
| `BOOKING_STAY_TOO_SHORT` | 400 | The current state does not allow it. |
| `BOOKING_STAY_TOO_LONG` | 400 | The current state does not allow it. |
| `BOOKING_UPLOAD_PENDING_LIMIT_EXCEEDED` | 429 | A limit was reached. |
| `BOOKING_IN_THE_PAST` | 400 | The current state does not allow it. |
| `BOOKING_HORIZON_EXCEEDED` | 400 | The current state does not allow it. |
| `BOOKING_DURATION_CEILING_EXCEEDED` | 400 | The current state does not allow it. |
| `BOOKING_PARTICIPANTS_NOT_SUPPORTED` | 400 | The current state does not allow it. |
| `BOOKING_PARTICIPANT_NOT_SEATED` | 400 | The current state does not allow it. |
| `BOOKING_RESOURCE_PARTICIPANTS_GROUP_CONFLICT` | 400 | The current state does not allow it. |
| `BOOKING_RESOURCE_CURRENCY_MISMATCH` | 400 | The current state does not allow it. |
| `BOOKING_OPENING_HOURS_SCHEDULE_NOT_FOUND` | 400 | The current state does not allow it. |
| `BOOKING_RESOURCE_GROUP_OUTSIDE_CONTEXT` | 400 | The current state does not allow it. |
| `BOOKING_ADD_ON_PRODUCT_IMAGE_REJECTED` | 400 | The current state does not allow it. |
| `BOOKING_ADD_ON_PRODUCT_RETIRED` | 400 | The current state does not allow it. |
| `BOOKING_ADD_ON_PRODUCT_RESOURCE_OUTSIDE_CONTEXT` | 400 | The request is not valid. |
| `BOOKING_ADD_ON_NOT_OFFERED` | 400 | The current state does not allow it. |
| `BOOKING_ADD_ON_DELIVERY_OUTSIDE_BOOKING` | 400 | The request is not valid. |
| `BOOKING_ADD_ON_DELIVERY_OUTSIDE_AVAILABILITY` | 400 | The current state does not allow it. |
| `BOOKING_ADD_ON_ORDER_LEAD_TOO_SHORT` | 400 | The current state does not allow it. |
| `BOOKING_ADD_ON_CUTOFF_PASSED` | 400 | The current state does not allow it. |
| `BOOKING_ADD_ON_SPECIAL_PORTIONS_INVALID` | 400 | The request is not valid. |
| `BOOKING_ADD_ON_LINE_LIMIT_EXCEEDED` | 400 | The current state does not allow it. |
| `BOOKING_ADD_ON_ON_INTERNAL_BOOKING` | 400 | The current state does not allow it. |
| `BOOKING_ADD_ON_LINE_NOT_FOUND` | 404 | It does not exist, or the token cannot see it. |
| `BOOKING_ADD_ON_LINE_DELIVERED` | 400 | The current state does not allow it. |
| `BOOKING_ADD_ON_LINE_NO_LONGER_FITS` | 400 | The current state does not allow it. |
| `BOOKING_ROOM_LAYOUT_NOT_OFFERED` | 400 | The current state does not allow it. |
| `BOOKING_ROOM_LAYOUT_CUTOFF_PASSED` | 400 | The current state does not allow it. |
| `BOOKING_ROOM_LAYOUT_NOT_CHANGEABLE` | 400 | The current state does not allow it. |
| `BOOKING_ROOM_SETUP_NOT_FOUND` | 404 | It does not exist, or the token cannot see it. |

### Billing

| Code | HTTP status | Meaning |
| --- | --- | --- |
| `BILLING_INTEGRATION_NOT_CONFIGURED` | 400 | The current state does not allow it. |
| `BILLING_INTEGRATION_GATE_NOT_DECLARED` | 400 | The current state does not allow it. |
| `BILLING_EXTERNAL_REFERENCE_ALREADY_USED` | 409 | It conflicts with something that already exists. |
| `BILLING_INVOICE_STATUS_INVALID` | 400 | The current state does not allow it. |
| `BILLING_PAYMENT_REPLAY_MISMATCH` | 409 | It conflicts with something that already exists. |
| `BILLING_PAYMENT_REVERSED` | 409 | It conflicts with something that already exists. |
| `BILLING_PAYMENT_NOT_FOUND` | 404 | It does not exist, or the token cannot see it. |
| `BILLING_PAYMENT_AMOUNT_INVALID` | 400 | The request is not valid. |
| `BILLING_WRITE_OFF_REPLAY_MISMATCH` | 409 | It conflicts with something that already exists. |
| `BILLING_WRITE_OFF_AMOUNT_INVALID` | 400 | The request is not valid. |
| `BILLING_PROPOSAL_STATUS_INVALID` | 400 | The current state does not allow it. |
| `BILLING_PROPOSAL_MATERIAL_ALREADY_INVOICED` | 409 | It conflicts with something that already exists. |
| `BILLING_CREDIT_NOTE_INVOICE_NOT_CREDITABLE` | 400 | The current state does not allow it. |
| `BILLING_CREDIT_NOTE_NO_PENDING_CORRECTIONS` | 400 | The current state does not allow it. |
| `BILLING_INVOICE_RUN_NOT_CONTINUABLE` | 400 | The current state does not allow it. |
| `BILLING_CREDIT_EXCEEDS_LINE` | 400 | The current state does not allow it. |
| `BILLING_CREDIT_EXCEEDS_INVOICE` | 400 | The current state does not allow it. |
| `BILLING_CREDIT_WITHHELD` | 400 | The current state does not allow it. |
| `BILLING_CREDIT_ACT_REPLAY_MISMATCH` | 400 | The request is not valid. |
| `BILLING_MANUAL_CREDIT_VAT_RATE_UNKNOWN` | 400 | The request is not valid. |
| `BILLING_CORRECTION_NOT_WITHDRAWABLE` | 400 | The current state does not allow it. |

### Signing

| Code | HTTP status | Meaning |
| --- | --- | --- |
| `CRM_CONTRACT_TEMPLATE_RETIRED` | 400 | The current state does not allow it. |
| `CRM_PACKAGE_RETIRED` | 400 | The current state does not allow it. |
| `CRM_PRODUCT_RETIRED` | 400 | The current state does not allow it. |
| `CRM_PRODUCT_UNKNOWN` | 400 | The current state does not allow it. |
| `CRM_AGENT_UNKNOWN` | 400 | The current state does not allow it. |
| `CRM_CUSTOMER_CHOICE_INVALID` | 400 | The request is not valid. |
| `CRM_PROSPECT_MATCHES_AGENT` | 409 | It conflicts with something that already exists. |
| `CRM_CUSTOMER_IS_AGENT` | 400 | The current state does not allow it. |
| `CRM_AGREEMENT_BILLING_DETAILS_REQUIRED` | 400 | The current state does not allow it. |
| `CRM_AGREEMENT_BILLING_ACCOUNT_EXISTS` | 400 | The current state does not allow it. |
| `CRM_AGREEMENT_BILLING_DETAILS_TYPE_MISMATCH` | 400 | The current state does not allow it. |
| `CRM_AGREEMENT_BILLING_DETAILS_INCOMPLETE` | 400 | The request is not valid. |
| `CRM_ROW_ACCESS_TERMS_INVALID` | 400 | The request is not valid. |
| `CRM_DEAL_LOST` | 400 | The current state does not allow it. |
| `CRM_DEAL_ACCEPTED` | 400 | The current state does not allow it. |
| `CRM_DEAL_TRANSITION_INVALID` | 400 | The current state does not allow it. |
| `CRM_DEAL_BUSINESS_CONTEXT_INVALID` | 400 | The current state does not allow it. |
| `CRM_PACKAGE_BUSINESS_CONTEXT_INVALID` | 400 | The current state does not allow it. |
| `CRM_PACKAGE_BUSINESS_CONTEXT_MISMATCH` | 400 | The current state does not allow it. |
| `CRM_PACKAGE_PRODUCT_DUPLICATE` | 400 | The request is not valid. |
| `CRM_PRODUCT_OUTSIDE_BUSINESS_CONTEXT` | 400 | The current state does not allow it. |
| `CRM_ROWS_EMPTY` | 400 | The current state does not allow it. |
| `CRM_ROWS_LIMIT` | 400 | The current state does not allow it. |
| `CRM_ROW_QUANTITY_INVALID` | 400 | The request is not valid. |
| `CRM_CURRENCY_MISMATCH` | 400 | The current state does not allow it. |
| `CRM_OFFER_TOKEN_INVALID` | 404 | It does not exist, or the token cannot see it. |
| `CRM_OFFER_EXPIRED` | 400 | The current state does not allow it. |
| `CRM_OFFER_ALREADY_ANSWERED` | 409 | It conflicts with something that already exists. |
| `CRM_OFFER_INVALIDATED` | 400 | The current state does not allow it. |
| `CRM_AGREEMENT_TRANSITION_INVALID` | 400 | The current state does not allow it. |
| `CRM_AGREEMENT_LOCKED` | 400 | The current state does not allow it. |
| `CRM_AGREEMENT_CANCELLED` | 400 | The current state does not allow it. |
| `CRM_AGREEMENT_START_DATE_MISSING` | 400 | The current state does not allow it. |
| `CRM_LEASABLE_UNIT_OCCUPIED` | 400 | The current state does not allow it. |
| `CRM_SIGNED_DOCUMENT_REJECTED` | 400 | The request is not valid. |
| `CRM_SIGNING_NOT_AVAILABLE` | 400 | The current state does not allow it. |
| `CRM_CONTRACT_BODY_MISSING` | 400 | The current state does not allow it. |
| `CRM_CONTRACT_VALUES_MISSING` | 400 | The current state does not allow it. |
| `CRM_CONTRACT_VARIABLE_UNKNOWN` | 400 | The request is not valid. |
| `CRM_CONTRACT_PLACEHOLDERS_OPEN` | 400 | The current state does not allow it. |
| `CRM_CONTRACT_RENDER_FAILED` | 400 | The current state does not allow it. |
| `CRM_SIGNING_ATTEMPT_LIVE` | 400 | The current state does not allow it. |
| `CRM_SIGNING_ATTEMPT_ENDED` | 409 | It conflicts with something that already exists. |
| `CRM_SIGNER_BUSINESS_CONTEXT_INVALID` | 400 | The current state does not allow it. |
| `CRM_SIGNER_NOT_ELIGIBLE` | 400 | The current state does not allow it. |
| `CRM_SIGNER_ALREADY_ADDED` | 409 | It conflicts with something that already exists. |
| `CRM_SIGNER_UNAVAILABLE` | 400 | The current state does not allow it. |
| `CRM_SIGNING_PARTY_REPEATED` | 400 | The request is not valid. |

### Integrations

| Code | HTTP status | Meaning |
| --- | --- | --- |
| `INTEGRATIONS_APP_INVALID` | 400 | The request is not valid. |
| `INTEGRATIONS_APP_ALREADY_EXISTS` | 409 | It conflicts with something that already exists. |
| `INTEGRATIONS_APP_INSTALLED` | 400 | The current state does not allow it. |
| `INTEGRATIONS_APP_ALREADY_INSTALLED` | 409 | It conflicts with something that already exists. |
| `INTEGRATIONS_CONSENT_MISMATCH` | 400 | The current state does not allow it. |
| `INTEGRATIONS_ROLE_NOT_GRANTABLE` | 400 | The current state does not allow it. |
| `INTEGRATIONS_CONTEXT_LEVEL_MISMATCH` | 400 | The current state does not allow it. |
| `INTEGRATIONS_CONFIGURATION_INVALID` | 400 | The request is not valid. |
| `INTEGRATIONS_POINT_ALREADY_FILLED` | 409 | It conflicts with something that already exists. |
| `INTEGRATIONS_CONFIGURATION_NOT_FOUND` | 404 | It does not exist, or the token cannot see it. |
| `INTEGRATIONS_CONNECTION_NOT_SUPPORTED` | 400 | The current state does not allow it. |
| `INTEGRATIONS_CONNECTION_REFERENCE_INVALID` | 400 | The request is not valid. |