2. Guides

Error Handling

This guide explains how integrators should read and react to errors returned by the TTDbooking OpenAPI.

HTTP Status Code vs Business Error Code

Errors are reported on two separate layers:

HTTP Status Code — the transport-level result of the request (200, 400, 401, etc.)
Business Error Code — an application-level code carried in the response body

Important: Treat the body's code field as authoritative. Reading the HTTP status alone is not enough.

HTTP Status Code Specification

HTTP Status	Meaning	Description
200	Success	Request processed successfully
400	Bad Request	Request parameter validation failed
401	Unauthorized	Invalid or expired token
403	Forbidden	No access to resource
404	Not Found	Requested resource not found
429	Too Many Requests	Exceeded request frequency limit
500	Internal Server Error	Internal server error
504	Gateway Timeout	Request processing timeout

Business Error Code Specification

Business error codes are structured as: [x][xx][xx][xxxx]

Error Code	HTTP Status	Meaning	Description
0	200	Success	Request successful
100000400	400	Parameter Error	Request parameter validation failed
100000401	401	Authentication Failed	Invalid or expired token
100000403	403	Permission Denied	No access to resource
100000404	404	Not Found	Requested resource not found
100000429	429	Rate Limited	Exceeded request frequency limit
100000500	500	System Error	Internal server error
100000504	504	Timeout	Request processing timeout
100001003	500	Duplicate Error	Duplicate resource or operation
100001004	500	Dependency Error	External dependency failure
100001005	400	Page Size Exceeded	Page size exceeds maximum limit
100001006	400	Not Implemented	Feature not implemented
100001007	400	Expired	Resource or token expired
100001008	400	Not Matched	Data does not match expected format
100001111	200	ARI Changed	Availability/rate information changed
100001112	200	Credit Limit	Reserved — not currently emitted (see note below)

100001112 (Credit Limit) is reserved and not currently emitted. No code path returns it today, so do not branch on it. A booking that would exceed a credit limit is currently refused as a 100000400 parameter error.

Error Response Format

Every error is returned in the same envelope:

json

{
  "code": 100000400,
  "msg": "param error"
}

Success Response Format

A successful call adds a data payload to that same envelope:

json

{
  "code": 0,
  "msg": "Success",
  "data": {
    // your response data
  }
}

Error Handling Best Practices

Branch your logic on body.code; reserve HTTP status codes for transport-level failures.
Expect application-level failures to arrive as HTTP 200 carrying a non-zero code.
Failures at the transport layer are signalled with the matching 4xx or 5xx HTTP status.
Drive retry decisions from the business error code rather than from the HTTP status alone.

Handling Non-Final Booking Status (Book API)

A common integration question: if a booking comes back with status of 1 (Confirming) or 0 (Unknown), should the request be rejected?

Short answer: do not reject immediately.

When a Book call returns HTTP 200, code=0, and data.hotelOrder.status is 1 or 0, proceed as follows.

Treat the response as valid and persist the identifiers:

customerReferenceNo
supplierReferenceNo (if present)

Resolve the outcome by calling QueryOrders — use customerReferenceNo where possible.
Interpret the status values with this rule:

1 (Confirming): still processing; not a final state.
0 (Unknown): indeterminate; must be verified.
2 (Confirmed): success.
3 (Cancelled), 4 (Failed), 5 (CancelFailed): final, unsuccessful.

Poll for up to roughly 10 minutes — for example immediately, then at 30s, 1m, 2m, and backing off from there.
Never re-submit a second booking for the same business intent while verification is still running.
If the status has not reached a final value once the polling window closes, leave the order pending and reach out to support with the stored references.

Support

For unresolved orders or questions about a specific error code, contact integrations@ttdbooking.com.

Full API reference: developer.ttdbooking.com/hotel-api/docs

Environments:

Production: api.ttdbooking.com
Test: api-test.ttdbooking.com

2. Guides

Export .md

Error Handling

This guide explains how integrators should read and react to errors returned by the TTDbooking OpenAPI.

HTTP Status Code vs Business Error Code

Errors are reported on two separate layers:

HTTP Status Code — the transport-level result of the request (200, 400, 401, etc.)
Business Error Code — an application-level code carried in the response body

Important: Treat the body's code field as authoritative. Reading the HTTP status alone is not enough.

HTTP Status Code Specification

HTTP Status	Meaning	Description
200	Success	Request processed successfully
400	Bad Request	Request parameter validation failed
401	Unauthorized	Invalid or expired token
403	Forbidden	No access to resource
404	Not Found	Requested resource not found
429	Too Many Requests	Exceeded request frequency limit
500	Internal Server Error	Internal server error
504	Gateway Timeout	Request processing timeout

Business Error Code Specification

Business error codes are structured as: [x][xx][xx][xxxx]

Error Code	HTTP Status	Meaning	Description
0	200	Success	Request successful
100000400	400	Parameter Error	Request parameter validation failed
100000401	401	Authentication Failed	Invalid or expired token
100000403	403	Permission Denied	No access to resource
100000404	404	Not Found	Requested resource not found
100000429	429	Rate Limited	Exceeded request frequency limit
100000500	500	System Error	Internal server error
100000504	504	Timeout	Request processing timeout
100001003	500	Duplicate Error	Duplicate resource or operation
100001004	500	Dependency Error	External dependency failure
100001005	400	Page Size Exceeded	Page size exceeds maximum limit
100001006	400	Not Implemented	Feature not implemented
100001007	400	Expired	Resource or token expired
100001008	400	Not Matched	Data does not match expected format
100001111	200	ARI Changed	Availability/rate information changed
100001112	200	Credit Limit	Reserved — not currently emitted (see note below)

100001112 (Credit Limit) is reserved and not currently emitted. No code path returns it today, so do not branch on it. A booking that would exceed a credit limit is currently refused as a 100000400 parameter error.

Error Response Format

Every error is returned in the same envelope:

json

{
  "code": 100000400,
  "msg": "param error"
}

Success Response Format

A successful call adds a data payload to that same envelope:

json

{
  "code": 0,
  "msg": "Success",
  "data": {
    // your response data
  }
}

Error Handling Best Practices

Branch your logic on body.code; reserve HTTP status codes for transport-level failures.
Expect application-level failures to arrive as HTTP 200 carrying a non-zero code.
Failures at the transport layer are signalled with the matching 4xx or 5xx HTTP status.
Drive retry decisions from the business error code rather than from the HTTP status alone.

Handling Non-Final Booking Status (Book API)

A common integration question: if a booking comes back with status of 1 (Confirming) or 0 (Unknown), should the request be rejected?

Short answer: do not reject immediately.

When a Book call returns HTTP 200, code=0, and data.hotelOrder.status is 1 or 0, proceed as follows.

Treat the response as valid and persist the identifiers:

customerReferenceNo
supplierReferenceNo (if present)

Resolve the outcome by calling QueryOrders — use customerReferenceNo where possible.
Interpret the status values with this rule:

1 (Confirming): still processing; not a final state.
0 (Unknown): indeterminate; must be verified.
2 (Confirmed): success.
3 (Cancelled), 4 (Failed), 5 (CancelFailed): final, unsuccessful.

Poll for up to roughly 10 minutes — for example immediately, then at 30s, 1m, 2m, and backing off from there.
Never re-submit a second booking for the same business intent while verification is still running.
If the status has not reached a final value once the polling window closes, leave the order pending and reach out to support with the stored references.

Support

For unresolved orders or questions about a specific error code, contact integrations@ttdbooking.com.

Full API reference: developer.ttdbooking.com/hotel-api/docs

Environments:

Production: api.ttdbooking.com
Test: api-test.ttdbooking.com