Testing & Rate Limits

Sandbox Mode

Use a test API key (pms_test_ prefix) to validate your integration without writing any data to the hotel’s system. When the hotel admin generates an API key, they receive both a live key and a test key as a pair. Ask the hotel admin for the test key to start development. Test keys run the exact same payload validation as live keys — every field rule in Error Handling applies identically.

Sandbox stops after payload validation. It does not reach the hotel’s actual guest list, so the conflict checks never run: you will not see ROOM_OCCUPIED, DUPLICATE_GUEST, ROOM_CLOSING or GUEST_NOT_FOUND in test mode, no matter what you send. Those are the responses most integrations handle badly, so exercise them against a live key on a hotel’s test property before you go into production.

Behavior	Live (`pms_live_`)	Test (`pms_test_`)
Payload validation	Full validation	Full validation
Conflict checks (room, duplicate)	Yes	No — never reached
Data written to database	Yes	No
Real-time dashboard updates	Yes	No
Response format	Real IDs	Fake IDs (`test_xxx`)
Rate limits	Normal	Same limits
Request logging	Yes	Yes (marked as test)

Test Response Example

{
  "status": "created",
  "guestId": "test_abc123",
  "pmsGuestId": "RES-2026-001",
  "roomNumber": "301",
  "requestId": "req_test_a1b2",
  "_sandbox": true
}

The _sandbox: true flag confirms you’re in test mode and no data was written. This flag is never present in live responses.

What to Test

Use sandbox mode to verify:

Payload format — Confirm all your field formats are correct (dates, phone numbers, etc.)
Error handling — Send intentionally invalid data to test your error handling code
Rate limit handling — Confirm your code handles 429 responses gracefully

Idempotency cannot be observed in sandbox. Test-mode responses are not stored, so resending the same key returns a fresh response rather than a replay, and _idempotent never appears. Send the header from the first day — it is required — but verify replay behaviour with a live key.

Recommended workflow: Develop and test with a pms_test_ key first. Once your integration passes all test cases, switch to the pms_live_ key for production. The only change needed is the API key — all endpoints and request formats are identical.

Idempotency

All POST endpoints require an Idempotency-Key header. This prevents duplicate operations when network issues cause retries — for example, if your system sends a check-in request but doesn’t receive the response due to a timeout, you can safely resend the same request.

How It Works

You include an Idempotency-Key header with every POST request
RecepAI processes the request and stores the response, keyed to your idempotency key
If you send another request with the same key to the same endpoint within 24 hours, RecepAI returns the cached response without re-processing

Rules

Rule	Detail
Required	All POST endpoints require this header. Omitting it returns `400`.
Length	1–255 characters
Scope	Keys are scoped to your API key and to the endpoint. Different hotels can use the same idempotency key safely, and the same key sent to two different endpoints never replays one endpoint’s response on the other.
TTL	Keys expire after 24 hours. After that, the same key can be reused.
Caching	Only 2xx responses are cached. If a request fails with 4xx, the key is NOT consumed — you can retry with a corrected payload using the same key.

Recommended Key Format

Use a structured format that’s unique per operation:

{operation}_{pmsGuestId}_{date}

Examples:

Operation	Idempotency Key
Check in guest RES-001 on Feb 18	`checkin_RES001_20260218`
Update guest RES-001 room change	`update_RES001_room_20260218`
Check out guest RES-001	`checkout_RES001_20260218`
Morning sync on Feb 19	`sync_20260219_morning`

Duplicate Response

When a cached response is returned, it includes an _idempotent flag:

{
  "status": "created",
  "guestId": "abc123-def456",
  "pmsGuestId": "RES-2026-001",
  "roomNumber": "301",
  "requestId": "req_a1b2c3d4",
  "_idempotent": true
}

The _idempotent: true flag tells you this is a cached replay, not a new operation. The response body, HTTP status, and requestId are all identical to the original response.

Important: Failed Requests Don’t Consume Keys

If your request returns a 4xx error (validation failure, room conflict, etc.), the idempotency key is not consumed. This means you can fix the issue and retry with the same key:

# First attempt — has a date format error
curl -X POST .../guests/checkin \
  -H "Idempotency-Key: checkin_RES001_20260218" \
  -d '{"checkOutDate": "18.02.2026"}'  # Wrong format!
# Returns 422 INVALID_DATE_FORMAT — key NOT consumed

# Second attempt — fixed payload, same key
curl -X POST .../guests/checkin \
  -H "Idempotency-Key: checkin_RES001_20260218" \
  -d '{"checkOutDate": "2026-02-18"}'  # Correct format
# Returns 200 — key now consumed with this response

Rate Limits

Each endpoint has its own rate limit. Limits are per hotel. One IP address may also send at most 600 requests a minute in total.

Limits by Endpoint

Endpoint	Limit
`POST /guests/checkin`	60 requests / minute
`POST /guests/update`	60 requests / minute
`POST /guests/checkout`	60 requests / minute
`GET /guests`	30 requests / minute
`POST /guests/sync`	10 requests / hour

Response Headers

Responses carry the endpoint’s rate limit in these headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1708180260

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Not every response carries them — a 429 from the per-IP limit never does. Read them when they are present.

Rate Limited Response (429)

When you exceed the limit:

HTTP/1.1 429 Too Many Requests
Retry-After: 45
Content-Type: application/json

{
  "status": "error",
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded. Retry after 45 seconds.",
  "retryAfter": 45,
  "requestId": "req_u1v2w3x4"
}

A 429 from the per-IP limit carries the same Retry-After header and body.

Handling Rate Limits

Implement exponential backoff in your integration:

async function callWithRetry(requestFn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await requestFn();

    if (response.status !== 429) {
      return response;
    }

    // Use the server's Retry-After value
    const data = await response.json();
    const waitSeconds = data.retryAfter || Math.pow(2, attempt);
    console.log(`Rate limited. Waiting ${waitSeconds}s before retry...`);
    await new Promise(r => setTimeout(r, waitSeconds * 1000));
  }

  throw new Error('Max retries exceeded');
}

For the sync endpoint (10/hour): Schedule your daily sync at a fixed time (e.g., 08:00). One sync per day is sufficient. For real-time updates throughout the day, use the individual check-in, update, and checkout endpoints which have much higher limits (60/minute).

Request Logging

Requests that reach an endpoint are logged — including test-mode requests — so support can answer “what did the PMS actually send us”. Retention: live-key requests are kept for 90 days, test-key requests for 30 days, after which they are deleted automatically. When contacting support, always include the requestId from the response — it is how a single call is found.

Security Notes

All API traffic is encrypted via HTTPS (TLS 1.2+). HTTP requests are rejected.
Treat the API key as a secret: send it in the Authorization header, never in a URL or a query string.
All guest changes from the PMS are recorded in an activity log with the actor type pms, visible alongside staff actions on the Front Desk.

Getting Started

Endpoints

Reference

Testing & Rate Limits

Sandbox Mode

Test Response Example

What to Test

Idempotency

How It Works

Rules

Recommended Key Format

Duplicate Response

Important: Failed Requests Don’t Consume Keys

Rate Limits

Limits by Endpoint

Response Headers

Rate Limited Response (429)

Handling Rate Limits

Request Logging

Security Notes

​Sandbox Mode

​Test Response Example

​What to Test

​Idempotency

​How It Works

​Rules

​Recommended Key Format

​Duplicate Response

​Important: Failed Requests Don’t Consume Keys

​Rate Limits

​Limits by Endpoint

​Response Headers

​Rate Limited Response (429)

​Handling Rate Limits

​Request Logging

​Security Notes

Sandbox Mode

Test Response Example

What to Test

Idempotency

How It Works

Rules

Recommended Key Format

Duplicate Response

Important: Failed Requests Don’t Consume Keys

Rate Limits

Limits by Endpoint

Response Headers

Rate Limited Response (429)

Handling Rate Limits

Request Logging

Security Notes