Error Codes Reference

All API errors follow a consistent JSON structure with a machine-readable code, HTTP statusCode, human-readable message, and optional details array for validation errors.

Error Response Structure

{
  "status": "ERROR",
  "error": {
    "code": "ERROR_CODE",
    "message": "Readable description",
    "statusCode": 400,
    "details": [ /* only present for INVALID_BOOKING_DATA */ ]
  },
  "meta": {
    "requestId": "req_...",
    "timestamp": "2025-07-10T09:30:00.000Z"
  }
}

Error Code Reference

HTTP	Error Code	Description	Resolution
`400`	`INVALID_REQUEST_BODY`	Request body is not valid JSON	Check `Content-Type: application/json` header and ensure body is valid JSON
`400`	`INVALID_BOOKING_DATA`	JSON schema validation failed	Inspect `details` array for per-field errors with `bookingCode`, `field`, and `message`
`401`	`UNAUTHORIZED`	Missing `x-api-key` or `x-account-id` headers	Ensure both authentication headers are present on every request
`403`	`INVALID_ACCOUNT`	Account ID not verified	Confirm your `x-account-id` value in the ZealConnect Portal
`403`	`INVALID_API_KEY`	API key doesn't match this account	Re-generate your API key in Settings → Integrations
`403`	`API_INTEGRATION_DISABLED`	API integration disabled for your org	Enable API integration in your ZealConnect Portal settings
`502`	`QUEUE_PUBLISH_FAILED`	Internal queue publish failure	Retry with exponential backoff. Contact support if persistent
`500`	`INTERNAL_SERVER_ERROR`	Unexpected server-side error	Retry once. If it persists, contact support with the `requestId`

Validation Error Details (INVALID_BOOKING_DATA)

When schema validation fails, the details array provides per-field errors:

{
  "status": "ERROR",
  "error": {
    "code": "INVALID_BOOKING_DATA",
    "message": "Schema validation failed",
    "statusCode": 400,
    "details": [
      {
        "bookingCode": "ZC-2025-00842",
        "field": "Guest.Adults",
        "value": -1,
        "message": "must be >= 0"
      },
      {
        "bookingCode": "ZC-2025-00843",
        "field": "Hotel.Name",
        "value": "",
        "message": "must NOT have fewer than 1 characters"
      }
    ]
  },
  "meta": {
    "requestId": "req-abc123",
    "timestamp": "2026-01-21T14:30:00.000Z"
  }
}

Retry Strategy

Implement exponential backoff for 5xx errors:

Start with 1 second delay

Double on each retry

Maximum delay: 60 seconds

Maximum retries: 5

Log the requestId from all error responses for support escalation

📧 Contact support at support@zealconnect.com and include your requestId for faster resolution.

Error Response Structure#

Error Code Reference#

Validation Error Details (INVALID_BOOKING_DATA)#

Retry Strategy#

Error Response Structure

Error Code Reference

Validation Error Details (INVALID_BOOKING_DATA)

Retry Strategy