Response Format

All Site Manager API responses follow a consistent JSON structure to ensure predictable handling across different endpoints.

Success Response Structure

A successful API response will have the following format:

Example 

{
  // Response payload varies by endpoint. The data field can be either an array or an object.
  "data":  []/{},
  "httpStatusCode": 200,
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}
  • The data object/array contains the actual response payload, which varies by endpoint.
  • The httpStatusCode field indicates the HTTP status of the response (usually 200 for success).
  • The traceId is a unique identifier for the request useful for troubleshooting.

Error Response Structure

All error responses follow this consistent format:

Example 

{
  "code": "NOT_FOUND",
  "httpStatusCode": 404,
  "message": "thing not found: 942A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:714694",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}
  • code: A machine-readable error code (uppercase string)
  • httpStatusCode: The HTTP status code (as a number)
  • message: A detailed description of the error
  • traceId: A unique identifier for the request (useful for troubleshooting)

Common Error Codes

HTTP Status Error Code Description Example Message
400 BAD_REQUEST The request was improperly formatted or contained invalid parameters “invalid request parameters”
401 UNAUTHORIZED Authentication failed or credentials are missing “unauthorized”
403 FORBIDDEN The authenticated user lacks permission to access the resource “insufficient permissions”
404 NOT_FOUND The requested resource does not exist “thing not found: {id}”
429 RATE_LIMIT The request exceeds the rate limit “rate limit exceeded, retry after 5.372786998s”
500 SERVER_ERROR An unexpected error occurred on the server “failed to get resource by ID”
502 BAD_GATEWAY The server received an invalid response from an upstream server “bad gateway”

Handling Errors

When handling errors from the API, we recommend:

  1. Check the HTTP status code first to determine the general category of error
  2. Parse the error code for programmatic handling of specific error conditions
  3. Log the traceId for all errors to assist with troubleshooting
  4. Implement retries with exponential backoff for 429 and 5xx errors
  5. Extract retry information from the header for rate limit errors
  6. Display user-friendly messages based on the error’s message

For rate limit errors, parse the retry time from the header and wait at least that long before retrying.