Error Handling

Error Response Format

Every error response follows the same structure:

{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "Human-readable description of what went wrong",
  "field": "fieldName",
  "requestId": "req_a1b2c3d4"
}

Field	Always Present	Description
`status`	Yes	Always `"error"`
`code`	Yes	Machine-readable error code (use this for programmatic handling)
`message`	Yes	Human-readable description (may change — don’t parse this)
`field`	No	Which field caused the error (only on validation errors)
`requestId`	Yes	Unique request ID for support inquiries

Always use the code field for error handling in your code, not message. The message text may be updated to be more helpful — the code will remain stable.

Error Codes

HTTP Status	Code	Description
400	`INVALID_JSON`	Request body is not valid JSON
400	`PAYLOAD_TOO_LARGE`	Request body is larger than 500 KB
400	`FIELD_REQUIRED`	A required field is missing. The `field` property tells you which one.
400	`FIELD_INVALID`	Field value is invalid (wrong type, out of range, too long, etc.)
400	`RESERVED_ROOM_SENTINEL`	`roomNumber` is `DAY`, which is reserved and cannot be used for a check-in
401	`UNAUTHORIZED`	Missing or invalid API key, including a key the hotel has revoked or regenerated. See Authentication.
403	`AGENT_NOT_INCLUDED`	Guest management is not enabled for this hotel. Stop sending guest updates and contact the hotel before retrying.
404	`GUEST_NOT_FOUND`	No active guest with the given `pmsGuestId`
409	`ROOM_OCCUPIED`	Room already has an active guest. Response includes `currentGuest` info.
409	`DUPLICATE_GUEST`	An active guest with the same `pmsGuestId` already exists
409	`ROOM_CLOSING`	The room is mid-checkout. Transient — retry.
409	`CHECKIN_CONFLICT`	Another check-in for the same room landed at the same moment. Transient — retry.
409	`SYNC_INCOMPLETE`	Part of a full sync was refused. The counts in the body are what actually happened. Retry the same sync to complete the rest.
422	`INVALID_DATE_FORMAT`	Date is not in ISO 8601 format (`YYYY-MM-DD`)
422	`INVALID_PHONE_FORMAT`	Phone number is not in E.164 format
429	`RATE_LIMITED`	Too many requests. See `Retry-After` header and Rate Limits.
500	`INTERNAL_ERROR`	Server error. The outcome is unknown — the operation may have landed. See Which errors to retry.
503	`SERVICE_UNAVAILABLE`	Temporarily unavailable. Nothing was processed. Retry after `retryAfter` seconds.
503	`CONFIGURATION_UNAVAILABLE`	Temporarily unavailable. Nothing was changed — retry.
503	`CHECKIN_PROFILE_FAILED`	Guest records are temporarily unavailable. Retry.
503	`STAY_UPDATE_FAILED`	An occupancy change could not be recorded. Nothing was updated — retry.

Validation Rules

Every field is validated on the server. One error is returned at a time — the first problem found. Fix it and resend to see the next, if there is one. Here are the rules for each field:

Field	Type	Constraints
`pmsGuestId`	string	Required. 1–255 characters. Must be unique among active guests.
`lastName`	string	Required. 1–100 characters.
`firstName`	string	Optional. 1–100 characters.
`roomNumber`	string	Required for check-in. 1–50 characters, string format (e.g., `"301"`, `"P2-105"`). `DAY` is reserved and rejected.
`phone`	string	Optional. Must be E.164 format (see below).
`checkInDate`	string	Optional (defaults to today). Must be `YYYY-MM-DD`.
`checkOutDate`	string	Required for check-in. Must be `YYYY-MM-DD`. Must be on or after `checkInDate`, and not in the past in the hotel’s own time zone — a hotel in Istanbul rolls over before one in New York.
`language`	string	Optional. Send an ISO 639-1 code (`en`, `tr`, `de`, `fr`, `es`, `ru`). Maximum 5 characters.
`nationality`	string	Optional. Send an ISO 3166-1 alpha-2 code (`US`, `TR`, `DE`). Maximum 5 characters.
`email`	string	Optional. Must be a valid email format.
`notes`	string	Optional. Maximum 2,000 characters.
`adults`	integer	Optional. Range: 1–20. Defaults to 1.
`children`	integer	Optional. Range: 0–20. Defaults to 0.
`guests`	array	Required for sync. At most 500 guests per request — a longer list returns `FIELD_INVALID`.

Date Format

Strict ISO 8601. No exceptions.

Format	Example	Status
`YYYY-MM-DD`	`2026-02-18`	Accepted
`DD.MM.YYYY`	`18.02.2026`	Rejected (422)
`MM/DD/YYYY`	`02/18/2026`	Rejected (422)
`DD-Mon-YYYY`	`18-Feb-2026`	Rejected (422)
Unix timestamp	`1708214400`	Rejected (422)

When a date fails validation, the error message includes what you sent and what’s expected:

{
  "status": "error",
  "code": "INVALID_DATE_FORMAT",
  "message": "Date must be in ISO 8601 format: YYYY-MM-DD. Received: '18.02.2026'",
  "field": "checkInDate",
  "requestId": "req_y5z6a7b8"
}

Many property management systems store or display dates as DD.MM.YYYY. Convert to YYYY-MM-DD before sending to RecepAI.

Phone Number Format

E.164 format required. Starts with +, followed by country code and number. No spaces, dashes, or parentheses.

Every phone number in these pages is drawn from the range reserved for documentation and fiction, so an example copied into a live test cannot reach a real person. A live check-in with a phone number can send that guest a welcome message — use your own number, or a reserved one, never a plausible-looking invented one.

Example	Status	Why
`+12025550143`	Accepted	Correct E.164
`+12025550168`	Accepted	Any country code is accepted
`+12025550172`	Accepted	Length varies by country
`2025550143`	Rejected	Missing country code
`+1 202 555 0143`	Rejected	Contains spaces
`0012-025-550-143`	Rejected	Contains dashes and leading zeros
`(202) 555-0143`	Rejected	Local format — not E.164

{
  "status": "error",
  "code": "INVALID_PHONE_FORMAT",
  "message": "Phone must be in E.164 format (+12025550143). Received: '2025550143'",
  "field": "phone",
  "requestId": "req_c3d4e5f6"
}

Common Mistakes

Sending dates in DD.MM.YYYY format

This is the most common error in the first days of an integration, and it comes from sending a date in the format the source system displays rather than converting it first.Fix: Convert all dates to YYYY-MM-DD before sending. For example, 18.02.2026 → 2026-02-18.

Missing country code on phone numbers

Sending 2025550143 instead of +12025550143. The phone field requires the full international number with country code.Fix: Prepend the country code with + — +90 for Turkey, +49 for Germany, +44 for the United Kingdom.

Sending roomNumber as an integer

Sending {"roomNumber": 301} instead of {"roomNumber": "301"}. Room numbers are strings because they can contain letters (e.g., "301A", "P2-105").Fix: Always send room numbers as strings: "301", not 301.

Forgetting the Idempotency-Key header

All POST endpoints require an Idempotency-Key header. Without it, you’ll receive a 400 error.Fix: Include Idempotency-Key: your_unique_key in every POST request. See Idempotency for key format recommendations.

Reusing the same Idempotency-Key for different operations

Each unique operation needs its own key. If you use the same key for two different guests on the same endpoint, the second request will return the first guest’s cached response.Fix: Use a key format like {operation}_{pmsGuestId}_{date}. Example: checkin_RES2026001_20260218.

Checking in a guest without checking out the previous one

If Room 301 still has an active guest and you try to check in a new guest to Room 301, you’ll get a 409 ROOM_OCCUPIED error.Fix: Always send a checkout for the departing guest before checking in the new guest. Or use the Full Sync endpoint which handles this automatically.

Handling Errors in Your Code

Here’s a recommended error handling pattern:

async function checkinGuest(slug, apiKey, guestData, idempotencyKey) {
  const response = await fetch(
    `https://app.recepai.ai/api/pms/v1/${slug}/guests/checkin`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': idempotencyKey
      },
      body: JSON.stringify(guestData)
    }
  );

  const data = await response.json();

  if (response.ok) {
    // Success — guest created (or idempotent replay)
    return data;
  }

  // Handle specific error codes
  switch (data.code) {
    case 'ROOM_OCCUPIED':
      // Room has another guest — check them out first
      console.log(`Room occupied by ${data.currentGuest.lastName}`);
      break;
    case 'DUPLICATE_GUEST':
      // Guest already checked in — maybe use update instead
      console.log(`Guest already exists: ${data.guestId}`);
      break;
    case 'RATE_LIMITED':
      // Wait and retry
      const retryAfter = data.retryAfter || 60;
      await sleep(retryAfter * 1000);
      return checkinGuest(slug, apiKey, guestData, idempotencyKey);
    case 'ROOM_CLOSING':
    case 'CHECKIN_CONFLICT':
      // Transient conflicts. The room is mid-checkout, or another request for
      // the same room landed at the same moment. Back off and resend the SAME
      // payload with the SAME idempotency key.
      await sleep(2000);
      return checkinGuest(slug, apiKey, guestData, idempotencyKey);
    case 'CONFIGURATION_UNAVAILABLE':
    case 'CHECKIN_PROFILE_FAILED':
    case 'STAY_UPDATE_FAILED':
    case 'SERVICE_UNAVAILABLE':
      // Nothing was changed. Retry with backoff.
      await sleep(5000);
      return checkinGuest(slug, apiKey, guestData, idempotencyKey);
    case 'AGENT_NOT_INCLUDED':
      // Not fixable from your side, ever. Stop and tell the hotel.
      console.error('This hotel cannot accept guest records — contact the hotel.');
      break;
    case 'FIELD_REQUIRED':
    case 'FIELD_INVALID':
    case 'INVALID_DATE_FORMAT':
    case 'INVALID_PHONE_FORMAT':
      // Fix your payload — don't retry with the same data
      console.error(`Validation error on ${data.field}: ${data.message}`);
      break;
    default:
      console.error(`Unexpected error: ${data.code} — ${data.message}`);
  }

  throw new Error(`PMS API error: ${data.code}`);
}

Which errors to retry

Do not decide this from the status code. Three 409 responses are transient and are meant to be retried, and one 403 can never succeed no matter how many times you send it. Branch on code.

Retry?	Codes	What to do
Yes, after a short pause	`ROOM_CLOSING` · `CHECKIN_CONFLICT`	The room is mid-checkout, or a concurrent request for the same room won the race. Resend the same payload with the same idempotency key.
Yes, and it completes the rest	`SYNC_INCOMPLETE`	Part of the sync landed and part was refused. The counts in the body are true. Sending the same sync again reconciles against the list as it now stands — this is the intended recovery, and the idempotency key is deliberately not consumed.
Yes, after `retryAfter`	`RATE_LIMITED`	Wait the number of seconds the response gives you.
Yes, with backoff	Every `503`	Nothing was changed. Back off (1s, 2s, 4s, 8s) and resend.
Yes — but the outcome is unknown	`INTERNAL_ERROR`	🔴 Do not read this as “nothing happened”. The operation may have landed and the failure occurred afterwards. Resend with the same idempotency key: an answer of `DUPLICATE_GUEST`, `GUEST_NOT_FOUND` or already checked out tells you the original did land. If you are still unsure, reconcile with a full sync. Include the `requestId` if you contact support.
No — fix the payload first	`FIELD_REQUIRED` · `FIELD_INVALID` · `INVALID_DATE_FORMAT` · `INVALID_PHONE_FORMAT` · `INVALID_JSON` · `PAYLOAD_TOO_LARGE` · `RESERVED_ROOM_SENTINEL`	The same payload will fail the same way. The `field` property names what to correct.
No — change the operation	`ROOM_OCCUPIED` · `DUPLICATE_GUEST` · `GUEST_NOT_FOUND`	The request is well formed but the hotel’s state disagrees with it. Check the guest out first, use `update` instead, or reconcile with a full sync.
No — not yours to fix	`AGENT_NOT_INCLUDED` · `UNAUTHORIZED`	Stop and contact the hotel. A retry loop here achieves nothing.

A retry is only safe because of the Idempotency-Key header. Always resend with the same key — a retry that mints a new key is a second operation, not a retry. See Idempotency.

Getting Started

Endpoints

Reference

Error Response Format

Error Codes

Validation Rules

Date Format

Phone Number Format

Common Mistakes

Handling Errors in Your Code

Which errors to retry

​Error Response Format

​Error Codes

​Validation Rules

​Date Format

​Phone Number Format

​Common Mistakes

​Handling Errors in Your Code

​Which errors to retry

Error Response Format

Error Codes

Validation Rules

Date Format

Phone Number Format

Common Mistakes

Handling Errors in Your Code

Which errors to retry