Vendor Sandbox - Concierge

Authentication

401 INVALID_SIGNATURE HMAC signature mismatch critical

The computed HMAC signature does not match the expected value.

Causes:

Wrong secret key
Body changed after signing
Clock skew > 5 minutes
Missing or extra whitespace in canonical string
Wrong encoding (must be UTF-8)

Fix: Verify your signing implementation against the reference. Check that the canonical string uses \n line separators and the body hash matches the exact body sent.

401 TOKEN_EXPIRED JWT access token expired Retryable critical

The bearer token has exceeded its 60-minute lifetime.

Causes:

Token older than 60 minutes
Token refresh not implemented
No expiry buffer (should refresh at 55 min)

Fix: Implement auto-refresh with a 55-minute buffer. On 401, fetch a new token via /vendor-api/auth/access_token and retry.

401 INVALID_TOKEN Invalid or malformed token Retryable critical

The bearer token is not a valid JWT or was not issued by this system.

Causes:

Corrupted token string
Using token from wrong environment
Token truncated in storage

Fix: Fetch a fresh token. Ensure you store the full token string without truncation.

401 MISSING_AUTH No authentication provided critical

The request is missing required authentication headers.

Causes:

No Authorization header
No HMAC headers
Wrong auth type (bearer vs HMAC)

Fix: Check which auth type the endpoint requires. HMAC endpoints need X-Signature headers; bearer endpoints need Authorization: Bearer {token}.

Customer

409 DUPLICATE_CUSTOMER Customer already exists info

A customer with this externalUserKey has already been accepted.

Causes:

Duplicate onboarding call
Retry after timeout (first call succeeded)

Fix: This is safe — the response returns the existing customerId. Use it to proceed.

400 INVALID_CUSTOMER_DATA Customer data validation failed warning

Required fields are missing or have invalid values.

Causes:

Missing firstName, lastName, dateOfBirth, or nationalityCountryIso3
Invalid date format (must be YYYY-MM-DD)
Invalid country code (must be ISO 3166-1 alpha-3)
Empty emails array

Fix: Check all required fields: externalUserKey, firstName, lastName, dateOfBirth, nationalityCountryIso3, emails (at least one).

429 RATE_LIMITED Rate limit exceeded Retryable warning

Too many requests in the current time window.

Causes:

Batch onboarding too fast (> 30/minute)
Aggressive polling
Missing rate limit delay

Fix: Add a 2-second delay between batch operations. For polling, use exponential backoff starting at 3 seconds.

Requests

400 INVALID_SERVICE_TYPE Unknown service type warning

The serviceId does not match any available service.

Causes:

Wrong serviceId value
Using deprecated service ID

Fix: Valid serviceIds: 1 (Transportation), 3 (Accommodation), 4 (Restaurant), 6 (Yacht), 7 (Event), 8 (Personal Assistance), 9 (Car Rental), 10 (Car with Driver).

400 INVALID_REQUEST_DETAILS Request details validation failed warning

The requestDetails object has missing or invalid fields for the selected service type.

Causes:

Missing required fields for service type
Invalid date format
Location not recognized

Fix: Each service type has specific required fields. Check documentation for the selected serviceId.

404 CUSTOMER_NOT_FOUND Customer not found critical

No customer exists for the authenticated token.

Causes:

Customer was deleted
Token belongs to a different customer
Customer not yet onboarded

Fix: Verify the customer was accepted via /vendor-api/accept-customer and the token was fetched for the correct externalUserKey.

Offers

200 NO_OFFERS No offers available yet Retryable info

The offers array is empty. Agents are still processing the request.

Causes:

Request recently created (< 2 min)
No suppliers match the criteria
Agents still searching

Fix: Keep polling every 5 seconds with exponential backoff. Timeout after 2 minutes. If still empty, the request may not be fulfillable.

404 OFFER_NOT_FOUND Offer not found or expired warning

The specified offer ID does not exist or has expired.

Causes:

Offer expired (they have limited validity)
Wrong offerId
Offer was withdrawn by supplier

Fix: Fetch fresh offers from the request-services endpoint and select a new one.

409 OFFER_ALREADY_SELECTED Offer already selected info

This offer has already been selected for checkout.

Causes:

Duplicate select call
Retry after timeout

Fix: Safe to ignore — the offer package was already created. Use the offerPackageId from the original response.

Checkout

404 PACKAGE_NOT_FOUND Offer package not found critical

The offer package ID does not exist.

Causes:

Wrong offerPackageId
Package was cancelled
Offer expired before package creation

Fix: Select a new offer to create a fresh package.

409 ALREADY_APPROVED Package already approved info

The offer package was already approved.

Causes:

Duplicate approve call

Fix: Safe to ignore — proceed to the next checkout step (prerequisites).

422 PREREQUISITES_NOT_MET Customer prerequisites incomplete critical

Required customer data is missing for this booking.

Causes:

Missing passport info
Passport expired before travel date
Missing contact information
Missing address

Fix: Check the prerequisites endpoint response for the missing[] array. Update the customer profile with the required data, then retry.

422 CHECKOUT_NOT_READY Checkout validation failed critical

The pre-check step found issues preventing checkout.

Causes:

Package not approved
Prerequisites not met
Offer expired
Contract not accepted (if required)

Fix: Ensure steps are executed in order: approve → prerequisites → precheck → contract → pay → complete.

410 OFFER_EXPIRED Offer no longer available critical

The offer has expired and can no longer be booked.

Causes:

Too much time between selection and payment
Supplier withdrew the offer

Fix: Create a new service request and select a new offer.

404 NO_CONTRACT No contract required info

This offer does not require a contract.

Causes:

Not all offers have contracts

Fix: This is not an error — skip the contract step and proceed to payment.

409 CONTRACT_ALREADY_ACCEPTED Contract already accepted info

The contract was already signed.

Causes:

Duplicate accept call

Fix: Safe to ignore — proceed to payment.

Payment

422 PAYMENT_METHOD_INVALID Invalid payment method warning

The payment method ID is invalid or expired.

Causes:

Method ID not found
Method expired or disabled
Wrong method type for this currency

Fix: Fetch fresh payment methods via GET /vendor-api/payment-methods and use one with status "active".

402 PAYMENT_DECLINED Payment was declined critical

The payment processor declined the transaction.

Causes:

Insufficient funds
Card expired
Fraud detection triggered
International transaction blocked

Fix: Prompt the customer for an alternative payment method. Do NOT retry the same method automatically.

409 DUPLICATE_PAYMENT Duplicate payment intent warning

A payment intent with this idempotency key already exists.

Causes:

Same idempotency key used twice
Retry of a successful payment

Fix: If the original payment succeeded, use its paymentIntentId. If it failed, generate a new idempotency key for the retry.

422 PAYMENT_NOT_CONFIRMED Payment not yet confirmed Retryable warning

Attempted to complete checkout before payment was confirmed.

Causes:

Calling checkout/complete before payment status is "succeeded"
Payment still processing

Fix: Poll GET /vendor-api/payment-intents/{id} until status is "succeeded", then call checkout/complete.

Chat

400 EMPTY_MESSAGE Message body is empty info

The message field is empty or missing.

Causes:

Empty string
Missing message field in body

Fix: Provide a non-empty message string in the request body.

429 CHAT_RATE_LIMITED Chat rate limit exceeded Retryable warning

Too many messages sent in a short period.

Causes:

More than 30 messages per minute

Fix: Queue messages and send max 1 per second.

General

500 INTERNAL_SERVER_ERROR Internal server error Retryable critical

An unexpected error occurred on the server.

Causes:

Backend bug
Database issue
Temporary outage

Fix: Retry with exponential backoff (1s, 2s, 4s). If persistent, check the Concierge status page or contact support.

503 SERVICE_UNAVAILABLE Service temporarily unavailable Retryable critical

The API is temporarily down for maintenance.

Causes:

Planned maintenance
Deployment in progress

Fix: Retry after 30 seconds. Check status page for maintenance windows.

Error Catalog & Diagnostics

Authentication

Customer

Requests

Offers

Checkout

Payment

Chat

General