Errors and response codes

How the API reports errors: HTTP response codes, the error body format and handling recommendations for the integration side.

The API uses standard HTTP response codes. The error body is in the ProblemDetails format (RFC 7807, the ASP.NET Core standard).

HTTP codes

Code	Meaning	When
`200 OK`	Success	The request completed, the body contains the result
`201 Created`	Created	The resource was created
`400 Bad Request`	Validation error	Invalid request body/parameters
`401 Unauthorized`	Not authenticated	The token is missing, expired or invalid
`402 Payment Required`	Payment required	The action is not available on the current plan/balance
`403 Forbidden`	No permission	No access to the restaurant or the action
`404 Not Found`	Not found	No resource with this identifier
`409 Conflict`	Conflict	Duplicate / state conflict (for example, creating the same thing twice)
`410 Gone`	Expired	The resource/code is no longer valid
`423 Locked`	Locked	The resource is temporarily locked
`429 Too Many Requests`	Too frequent	The request limit was exceeded — back off
`503 Service Unavailable`	Unavailable	Temporarily unavailable — retry later

Error body format

An error response is a ProblemDetails object:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "detail": "Problem description",
  "instance": "/api/rsv/admin/restaurants/123/reservations"
}

Field	Type	Description
`type`	string	Link to the problem type
`title`	string	Short error title
`status`	integer	HTTP code
`detail`	string	Detailed description (if any)
`instance`	string	Path of the request that caused the error

The object allows extra fields (additionalProperties) — for example, on validation errors an errors dictionary with a per-field breakdown may be present.

Handling recommendations

401 — get a new token and retry the request. Do not treat 401 as “resource not found”.
403 — check that the account has access to the given restaurantId.
400 — read detail/errors; fix the request, do not retry it “as is”.
404 — check the identifiers in the path (especially string reservation/guest IDs).
409 — a duplicate is likely; before retrying, check whether the resource was already created (GET).
429 / 503 — retry with exponential backoff, not immediately.

Retries

Code	Retry?	How
`429`, `503`	Yes	Exponential backoff (for example, 1s → 2s → 4s), with a cap on attempts
`5xx` (others)	Carefully	Only idempotent GETs; for POST — first check whether it was created
`400`, `401`, `403`, `404`, `409`	No	These are request/permission errors — retrying unchanged will not help

When retrying POST requests that create something, make sure you are not creating a duplicate — see Conventions → Idempotency.