| Field | Type | Description |
|---|---|---|
| `success` | `boolean` | Always `false` for error responses |
| `statusCode` | `number` | HTTP status code mirrored in the body for logging convenience |
| `errorCode` | `string` | Structured Travelbase error code — the primary field for programmatic handling |
| `message` | `string` | Human-readable summary of the error |
| `fault` | `"client" \| "server"` | Whether the error originated from your request or from Travelbase infrastructure |
| `retryable` | `boolean` | Whether retrying the same request may succeed — safe to use for automated retry logic |
| `suggestedAction` | `string` | Recommended next step for resolution — safe to display to support staff |
| `reason` | `string \| FieldError[]` | String for most errors; array of field-level objects for validation failures |
| `environment` | `"sandbox" \| "production"` | Confirms which environment the error occurred in |
| `apiVersion` | `string` | The API version that processed the request |
`. This makes it easy to handle entire categories with a single prefix check before falling through to specific codes.
### Authentication — `TB_AUTH_*`
Code
Name
HTTP
Retryable
Resolution
`TB_AUTH_100`
AUTH\_MISSING
401 No
Include an `Authorization: Bearer ` header on the request
`TB_AUTH_101`
AUTH\_INVALID
401 No
Check the API key value — verify it matches exactly what was issued in the dashboard
`TB_AUTH_102`
AUTH\_EXPIRED
401 Yes
Refresh the access token using your refresh token, then replay the request
`TB_AUTH_103`
AUTH\_BLOCKED
403 No
Account has been suspended — contact Travelbase support to investigate
`TB_AUTH_104`
SESSION\_EXPIRED
401 Yes
Session has lapsed — prompt the traveller to re-authenticate and retry
### Permissions — `TB_PERM_*`
Code
Name
HTTP
Retryable
Resolution
`TB_PERM_200`
ACCESS\_DENIED
403 No
The authenticated identity does not have permission for this resource — check your API key scope or role assignment
`TB_PERM_201`
ACTION\_NOT\_ALLOWED
403 No
This action is not permitted in the current account state or tier — review your plan and enabled features
### Validation — `TB_VAL_*`
Code
Name
HTTP
Retryable
Resolution
`TB_VAL_300`
INVALID\_INPUT
400 No
A request field contains an unacceptable value — consult the endpoint schema and correct the payload
`TB_VAL_301`
FIELD\_FORMAT\_INVALID
400 No
A field does not match the expected format (e.g. date as `YYYY-MM-DD`, phone in E.164 format)
`TB_VAL_302`
VALIDATION\_ERROR
400 No
One or more required fields are missing — inspect the `reason` array for field-level detail
`TB_VAL_303`
DUPLICATE\_RESOURCE
409 No
A resource with an identical unique key already exists — retrieve the existing record instead of creating a new one
### Resources — `TB_RES_*`
Code
Name
HTTP
Retryable
Resolution
`TB_RES_400`
RESOURCE\_NOT\_FOUND
404 No
The booking, flight, hotel, or traveller record does not exist or is not accessible by this key
`TB_RES_401`
RESOURCE\_EXISTS
409 No
You are attempting to create something that already exists — use an update operation instead
`TB_RES_402`
RESOURCE\_STATE\_INVALID
409 No
The resource is in a state that does not allow this action (e.g., cancelling an already-departed booking) — check the resource's current `status` field
### System — `TB_SYS_*`
Code
Name
HTTP
Retryable
Resolution
`TB_SYS_600`
INTERNAL\_ERROR
500 Yes
An unexpected server-side error occurred — retry with exponential backoff; escalate to support if it persists
`TB_SYS_602`
UNSUPPORTED\_ACTION
400 No
The operation is not supported for this resource type or API version — review the changelog for deprecations
`TN_ISE_901`
INTERNAL\_SERVER\_ERROR
500 Yes
Critical infrastructure error — contact support with the full response body and request ID
### Rate & Quota Limits — `TB_LIM_*`
Code
Name
HTTP
Retryable
Resolution
`TB_LIM_700`
RATE\_LIMIT\_EXCEEDED
429 Yes
Too many requests in the current window — back off and retry after the `Retry-After` header value (in seconds)
`TB_LIM_701`
QUOTA\_EXCEEDED
429 No
Your plan's monthly booking or search quota has been reached — upgrade your plan or wait for the quota reset
`TB_LIM_702`
TOO\_MANY\_ATTEMPTS
429 Yes
Too many failed authentication attempts — wait for the lockout window to expire before retrying
### Payments — `TB_PAY_*`
Payment errors require careful handling. Always check `retryable` before attempting a retry — retrying a non-retryable payment error can result in multiple authorisation holds on a traveller's card.
Code
Name
HTTP
Retryable
Resolution
`TB_PAY_800`
PAYMENT\_FAILED
402 No
The payment was declined by the issuing bank — prompt the traveller to use a different payment method
`TB_PAY_801`
PAYMENT\_METHOD\_UNSUPPORTED
400 No
The payment method type is not accepted for this booking type or region — present a supported alternative
`TB_PAY_802`
REFUND\_FAILED
500 Yes
The refund could not be processed — retry once; if it fails again, escalate to Travelbase support with the order ID
### Tenant Status — `TENANT_*`
These errors apply when your platform operates in a multi-tenant context. They reflect the operational status of the tenant account making the request.
Code
HTTP
Meaning
Resolution
`TENANT_PENDING_APPROVAL`
403 Tenant account is awaiting onboarding review
No action needed — await the approval email from the Travelbase partnerships team
`TENANT_REJECTED`
403 Tenant application was not approved
Contact [partnerships@travelbase.com](mailto:partnerships@travelbase.com) to understand the reason and whether reapplication is possible
`TENANT_SUSPENDED`
403 Tenant account has been suspended due to a policy or compliance issue
Contact support immediately — active bookings may be at risk
`TENANT_UNAVAILABLE`
503 Tenant services are temporarily unavailable
Retry with backoff — this is typically a transient infrastructure state
***
## Handling Errors in Code
The following patterns cover the full error handling lifecycle for a Travelbase integration.
```ts theme={null}
import type { TravelbaseError, FieldError } from "@travelbase/sdk";
async function createBooking(payload: BookingPayload) {
try {
return await travelbase.bookings.create(payload);
} catch (err) {
if (!isTravelbaseError(err)) throw err;
return handleTravelbaseError(err);
}
}
function handleTravelbaseError(error: TravelbaseError) {
const { errorCode, retryable, suggestedAction } = error;
// Authentication — token has lapsed mid-session
if (errorCode === "TB_AUTH_102" || errorCode === "TB_AUTH_104") {
return refreshTokenAndRetry();
}
// Validation — surface field-level errors back to the booking form
if (errorCode === "TB_VAL_302" && Array.isArray(error.reason)) {
for (const field of error.reason as FieldError[]) {
setFormError(field.field, field.message);
}
return;
}
// Payment declined — prompt traveller to use another card
if (errorCode === "TB_PAY_800") {
return showPaymentDeclinedModal();
}
// Rate limit — respect the Retry-After header
if (errorCode === "TB_LIM_700") {
const retryAfter = error.headers?.["retry-after"] ?? 60;
return scheduleRetry(retryAfter * 1000);
}
// Tenant issues — operational block, not a code bug
if (errorCode.startsWith("TENANT_")) {
return showTenantStatusBanner(errorCode);
}
// Server-side retryable errors
if (error.fault === "server" && retryable) {
return retryWithBackoff(createBooking, payload);
}
// Non-retryable client errors — log and surface the suggestion
console.error(`[Travelbase] ${errorCode}: ${suggestedAction}`);
throw error;
}
```
```python theme={null}
from travelbase import TravelbaseError
def create_booking(payload: dict):
try:
return travelbase.bookings.create(payload)
except TravelbaseError as err:
return handle_travelbase_error(err)
def handle_travelbase_error(err: TravelbaseError):
code = err.error_code
if code in ("TB_AUTH_102", "TB_AUTH_104"):
return refresh_token_and_retry()
if code == "TB_VAL_302" and isinstance(err.reason, list):
for field_error in err.reason:
set_form_error(field_error["field"], field_error["message"])
return
if code == "TB_PAY_800":
return show_payment_declined()
if code == "TB_LIM_700":
retry_after = int(err.headers.get("retry-after", 60))
return schedule_retry(delay_seconds=retry_after)
if code.startswith("TENANT_"):
return show_tenant_status_banner(code)
if err.fault == "server" and err.retryable:
return retry_with_backoff(create_booking, payload)
raise err
```
```go theme={null}
func createBooking(payload BookingPayload) (*Booking, error) {
booking, err := client.Bookings.Create(payload)
if err == nil {
return booking, nil
}
tbErr, ok := err.(*TravelbaseError)
if !ok {
return nil, err
}
switch tbErr.ErrorCode {
case "TB_AUTH_102", "TB_AUTH_104":
return refreshAndRetry(payload)
case "TB_VAL_302":
return nil, formatValidationErrors(tbErr.Reason)
case "TB_PAY_800":
return nil, ErrPaymentDeclined
case "TB_LIM_700":
retryAfter := tbErr.RetryAfterSeconds(60)
time.Sleep(time.Duration(retryAfter) * time.Second)
return createBooking(payload)
}
if strings.HasPrefix(tbErr.ErrorCode, "TENANT_") {
return nil, fmt.Errorf("tenant issue: %s", tbErr.ErrorCode)
}
if tbErr.Fault == "server" && tbErr.Retryable {
return retryWithBackoff(createBooking, payload)
}
return nil, tbErr
}
```
***
## Retry Strategy
Not every error should be retried. Use `retryable: true` as your gate, then apply exponential backoff to avoid overwhelming the API during degraded conditions.
```ts theme={null}
async function retryWithBackoff(
fn: () => Promise,
maxAttempts = 4,
baseDelayMs = 300
): Promise {
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
try {
return await fn();
} catch (err) {
const isLast = attempt === maxAttempts;
const isRetryable = isTravelbaseError(err) && err.retryable;
if (isLast || !isRetryable) throw err;
const delay = baseDelayMs * 2 ** (attempt - 1); // 300ms → 600ms → 1.2s → 2.4s
const jitter = Math.random() * 100;
await sleep(delay + jitter);
}
}
throw new Error("Unreachable");
}
```
Add random jitter (a small random offset on top of the delay) to prevent a thundering herd — many clients retrying in perfect lockstep can amplify an outage rather than recover from it.
***
## Decision Tree
When you receive an error, follow this path to resolution:
`"client"` means your request needs to change before retrying. `"server"` means the problem is on Travelbase's side and may resolve on its own.
If `false`, do not retry — fix the request first. If `true`, proceed to backoff.
Use the catalog above to understand the exact cause. Handle auth, validation, payments, and tenant errors with dedicated logic paths.
Surface this field to internal support tooling or operations dashboards. It is written for humans, not machines.
For `TB_SYS_600`, `TN_ISE_901`, `TB_PAY_802`, or persistent `TENANT_SUSPENDED`, open a support ticket with the full error body and your request ID.
***
## Common Mistakes
| Mistake | Consequence | Fix |
| ------------------------------------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Retrying non-retryable errors in a loop | Duplicate charges, burnt quota, account lockout | Always check `retryable: false` before retrying |
| Swallowing `TB_RES_402` (invalid resource state) | Attempting to cancel a departed flight silently fails | Check the booking's `status` field before mutating it |
| Ignoring `TENANT_SUSPENDED` | All bookings for affected travellers are silently blocked | Monitor for tenant codes and alert your operations team immediately |
| Using `message` for programmatic branching | Prone to breaking if copy changes | Always branch on `errorCode`, never on `message` |
| Not reading the `reason` array on `TB_VAL_302` | Generic "something went wrong" shown to travellers | Map `reason` fields directly to your booking form for inline feedback |
| Retrying `TB_PAY_800` automatically | Multiple authorisation holds on the traveller's card | Payment declines require human action — prompt for a different payment method |
***
## TypeScript Error Code Enum
Copy this enum directly into your project for compile-time safety across all error handling code:
```ts theme={null}
export enum TravelbaseErrorCode {
// Authentication
AUTH_MISSING = "TB_AUTH_100",
AUTH_INVALID = "TB_AUTH_101",
AUTH_EXPIRED = "TB_AUTH_102",
AUTH_BLOCKED = "TB_AUTH_103",
SESSION_EXPIRED = "TB_AUTH_104",
// Permissions
ACCESS_DENIED = "TB_PERM_200",
ACTION_NOT_ALLOWED = "TB_PERM_201",
// Validation
INVALID_INPUT = "TB_VAL_300",
FIELD_FORMAT_INVALID = "TB_VAL_301",
VALIDATION_ERROR = "TB_VAL_302",
DUPLICATE_RESOURCE = "TB_VAL_303",
// Resources
RESOURCE_NOT_FOUND = "TB_RES_400",
RESOURCE_EXISTS = "TB_RES_401",
RESOURCE_STATE_INVALID = "TB_RES_402",
// Bad Request
BAD_REQUEST = "TB_BR_403",
// System
INTERNAL_ERROR = "TB_SYS_600",
UNSUPPORTED_ACTION = "TB_SYS_602",
INTERNAL_SERVER_ERROR = "TN_ISE_901",
// Limits
RATE_LIMIT_EXCEEDED = "TB_LIM_700",
QUOTA_EXCEEDED = "TB_LIM_701",
TOO_MANY_ATTEMPTS = "TB_LIM_702",
// Payments
PAYMENT_FAILED = "TB_PAY_800",
PAYMENT_METHOD_UNSUPPORTED = "TB_PAY_801",
REFUND_FAILED = "TB_PAY_802",
// Tenant
TENANT_PENDING_APPROVAL = "TENANT_PENDING_APPROVAL",
TENANT_REJECTED = "TENANT_REJECTED",
TENANT_SUSPENDED = "TENANT_SUSPENDED",
TENANT_UNAVAILABLE = "TENANT_UNAVAILABLE",
}
```
***
## Related
* [Idempotency & Retries](/docs/idempotency-retries)
* [Webhooks](/docs/webhooks)
* [Rate Limits](/docs/rate-limits)
* [Booking Lifecycle](/docs/booking-lifecycle)
* [Payment Methods](/docs/payment-methods)