Errors use conventional HTTP status codes, with a JSON body:
{ "detail": "Order 6c1f… not found" }Status codes
| Status | Meaning | What to do |
|---|---|---|
400 | The request is well-formed but cannot be carried out as sent | Read detail, fix the request |
401 | The access token or staff token is missing, expired or invalid, or the PIN is wrong | Refresh the token, or sign the staff member in again |
403 | Authenticated, but not allowed: the property is not in the token, the staff and access tokens belong to different properties, or the operation needs management access | Use a token with the right access |
404 | Not found at this property | Check the id and x-property-id |
409 | Conflicts with the current state: paying a cancelled order, deleting a role still in use, freeing a table with an open order, reusing an idempotency key with a different payload | Reload the resource, then decide |
422 | Validation failed | detail lists each failing field |
429 | Too many failed PIN attempts on this device | Wait a few minutes |
502 | A Cloudbeds service the operation depends on failed | Retry later |
503 | A dependency is temporarily unavailable, for example tax rates when pricing a cart | Retry later; the API does not return estimates |
Operations that need an approval reject an
approval_token that is missing, expired, already used, or granted for a
different action or record. Ask for a new approval.
Validation errors
{
"detail": [
{
"loc": ["body", "items", 0, "quantity"],
"msg": "Input should be greater than or equal to 1",
"type": "greater_than_equal"
}
]
}Charge to Room error codes
The /pos/charges operations return a structured detail:
{
"detail": {
"code": "idempotency_conflict",
"message": "This charge is still being processed. Try again in a moment.",
"retryable": true
}
}retryable says whether sending the same request again could succeed. message
is written for the person at the terminal and can be shown as is.
code | Status | Meaning |
|---|---|---|
missing_idempotency_key | 400 | The Idempotency-Key header is missing |
unknown_target | 400 | The reservation or group was not found |
blocked_target | 400 | The target cannot be charged right now, for example because the guest has checked out |
nothing_to_charge | 400 | The order has nothing to post |
mapping_error | 400 | The provider's order could not be read |
account_property_mismatch | 403 | The terminal's merchant belongs to a different property |
integration_disconnected | 403 | The terminal's merchant is not connected to this property |
not_found | 404 | No charge exists for this order (void and gratuity) |
idempotency_conflict | 409 | Another request with this key is still in progress (retryable: true), or the key was used for a different charge (retryable: false) |
charge_voided | 409 | The charge was voided. Charge again with a new key. |
folio_post_failed | 502 | Cloudbeds did not accept the posting. Nothing was posted. Check retryable. |