Errors

SmartOrder Open API business endpoints use a standard response envelope for both successful and failed requests. A failed response has the following structure:

{
  "code": "400",
  "msg": "Invalid request",
  "data": null,
  "tid": "7f3d9a1c2b4e"
}

Field	Description
`code`	Stable error category. `0` indicates success; any other value indicates failure
`msg`	Human-readable English description of the specific failure scenario
`data`	Response data on success and `null` on failure
`tid`	Trace identifier to include when contacting SmartOrder support

Use code for programmatic branching and msg for diagnostics or user-facing context. Multiple failure scenarios share the same code when they belong to the same error category.

Error code reference

Code	HTTP status	Category	When it occurs	What to do
`400`	400	Parameter error	The JSON body is malformed, a required field is missing, or a field value or combination is invalid	Fix the request according to `msg`; do not retry unchanged
`401`	401	Authentication error	The Bearer token is missing, invalid, expired, or does not identify an enabled Open API application	Obtain a valid access token and retry
`403`	403	Authorization error	The application is authenticated but is not authorized for the requested `hotelId`	Verify the hotel authorization; do not retry unchanged
`422`	422	Business error	The request is valid but cannot be completed because of the current resource or downstream business state	Handle the scenario described by `msg`; retry only when the condition can change
`500`	500	System error	An unexpected server error or unmapped downstream error occurs	Retry with backoff. Contact support with the `tid` if the error persists

Scenario messages

The following messages describe current API scenarios. New scenarios can reuse an existing error category without introducing another public error code.

Code	Example `msg`	Scenario
`400`	`Invalid message content`	Message `content` does not match its `msgType`, text is empty or too long, or an image URL is invalid
`400`	`Exactly one of clientMessageId and messageId must be provided`	A message detail request provides both query identifiers or neither identifier
`422`	`Message not found`	No message is found for the supplied identifier
`422`	`Thread not found`	No thread is found in the authorized hotel context
`422`	`Failed to submit message`	The messaging service does not return a message identifier

OAuth token errors

The Obtain an access token endpoint follows the OAuth error format instead of the standard business response envelope:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Use error for programmatic handling. error_description provides human-readable details and can be absent.

Common scenarios

A request returns HTTP 401

Confirm that the header uses Authorization: Bearer <access_token>, contains no extra whitespace, and carries a token issued by the configured test token endpoint. Request a new token if the current token has expired.

A request returns HTTP 403

The token is valid, but the application does not have access to the request's hotelId. Contact the SmartOrder administrator responsible for the application's hotel authorization.

A request returns `400` or `422`

Use code to select the handling category, then use msg to explain the specific scenario. Do not build client control flow by matching message text.

Contacting support

Include the following information when reporting a persistent error:

The response tid.
The approximate request time and timezone.
The HTTP method and path.
The HTTP status, code, and msg.
The expected and observed behavior.

Do not include access tokens, client_secret, or other credentials.