Error Handling

APIs in the CloudHub platform return structured error responses whenever possible. Your integration should parse the response body, log the HTTP status and error details, and apply retry logic only for transient failures.

HTTP status codes

Status	Meaning	Typical cause
400 Bad Request	The request was malformed or failed validation	Missing required fields, invalid JSON, unsupported query options, or business-rule violations
401 Unauthorized	Authentication failed	Missing, expired, or invalid Bearer token; Authorization header not prefixed with Bearer
403 Forbidden	Authenticated but not permitted	Invalid or missing InternalProductKey on direct CHC calls; license validation failure
404 Not Found	Resource does not exist	Invalid entity ID, wrong endpoint path, or record not found in the tenant database
422 Unprocessable Entity	Request is syntactically valid but cannot be processed	Data conflicts or domain validation failures on some OData write operations
500 Internal Server Error	Unexpected server error	Downstream CHC or database failure; retry with backoff

For authentication and licensing errors specific to each access path, see the Access guide.

OData API and OrderCreate API

The OData API returns errors using a TrimbleErrorResponse envelope:

{
  "errors": [
    {
      "code": "400",
      "domain": "Transportation.OData",
      "description": "The request contains the following validation errors: ...",
      "lang": "en-US",
      "requestId": "00000000-0000-0000-0000-000000000000",
      "timeStamp": "2026-07-20T12:00:00Z",
      "link": {
        "rel": "help",
        "href": "https://developer.trimble.com"
      }
    }
  ]
}

Each item in the errors array includes a human-readable description. Check this field first when debugging failed requests. The requestId and timeStamp values are useful when opening a support case.

The OrderCreate API uses the same ASP.NET Core pipeline. Validation failures (for example, missing billTo, shipper, or consignee on a canonical order request) and business-rule violations (for example, referencing a leg or stop that does not exist) are returned as 400 Bad Request with a message describing the failure.

OData list endpoints may also return OData error payloads for query issues. When using $filter, $select, $expand, or $orderby, confirm the property names and types match the entity definition in the OData OpenAPI definition. Dynamic Query batch updates (POST /tte-tmwsuite/v0/odata/dynamicQuery/update/batch) also return TrimbleErrorResponse on 400.

CloudHub API

Error responses on CloudHub API operations use the StandardTrimbleErrorV2 schema (type, title, status, instance, detail, and a nested errors array):

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Company ID is required."
}

List and read operations typically return 200; create operations return 201. Some updates return 202, and some contact reads may return 206. Failed requests use 400 (validation) or 404 (resource not found). Refer to the CloudHub OpenAPI definition for the response schema on each operation.

Direct Cloud Hub Connector access

When calling CHC directly (not through TTC), license errors are returned as plain-text messages with HTTP 403 Forbidden:

Message	Cause
Missing License!	InternalProductKey header was not supplied
License validation failed!	Header is invalid, malformed, or expired (approximately 15-minute TTL)

Recommended client behavior

1. Read the response body on every non-2xx response. Do not rely on the status code alone.
2. Log requestId from Trimble error objects when reporting issues to support.
3. Retry only transient errors — use exponential backoff for 500, 502, 503, and 504. Do not retry 400, 401, 403, or 404 without changing the request.
4. Refresh tokens proactively — obtain a new access token before the current one expires rather than waiting for 401 responses.
5. Validate payloads locally before sending write requests, especially for OrderCreate dispatch operations that create multiple related records in a single call.

See Best Practices for guidance on pagination, payload size, and resilient integration patterns. For symptom-based diagnosis, see Troubleshooting.