Troubleshooting

Use this guide to diagnose common integration issues. For error response formats and HTTP status code meanings, see Error Handling.

Symptom	Likely cause	What to check
401 Unauthorized on every TTC request	Token missing, expired, or malformed	Confirm `Authorization: Bearer {access_token}` is set; request a new token from Trimble Identity
401 immediately after token request	Wrong scope or credentials	Use `grant_type=client_credentials` with scope `sas_token` and the correct client ID and secret
403 Forbidden on direct CHC calls	License header issue	Supply a valid `InternalProductKey` header; confirm it has not expired (~15 minutes)
Requests reach the wrong tenant’s data	CloudHub configuration mismatch	Verify the account’s CloudHub configuration record points to the correct CHC OData endpoint — see CloudHub Configuration

Symptom	Likely cause	What to check
Empty result set	Overly restrictive `$filter`	Test without filters first, then narrow incrementally
400 Bad Request on list endpoints	Invalid OData query syntax	Verify property names, operators, and quoting in `$filter` and `$orderby`; check the OpenAPI definition for supported query options
400 on write operations	Validation failure	Read the `errors[].description` field in the `TrimbleErrorResponse` body
Slow or timed-out responses	Payload or result set too large	Reduce `limit`, use `$select` to return fewer fields, and paginate — see Best Practices

Symptom	Likely cause	What to check
404 Not Found on GET by ID	Record does not exist in the tenant database	Confirm the ID is correct for the configured customer environment
400 Bad Request on POST or PUT	Required field missing or invalid	Check `title` and `detail` in the `StandardTrimbleErrorV2` body; compare your payload to the schema in the OpenAPI definition
Empty or truncated list results	Pagination or filter too narrow	Adjust `pageSize` (maximum 100) and `pageIndex`; `$select` is unsupported
Inconsistent results between environments	Different tenant configuration	Dev and production TTC environments use separate accounts and CloudHub configuration records

Symptom	Likely cause	What to check
400 on `create-order-canonical-model`	Missing required order fields	`billTo`, `shipper`, and `consignee` are required on every canonical order request
400 referencing a leg, stop, or order	Entity not found	Confirm the referenced `ord_hdrnumber`, `lgh_number`, or `stp_number` exists in the tenant database
400 on freight payload	Invalid quantity fields	Each freight line needs a valid measure (weight, count, quantity, volume, or dimensions with units) — see the OrderCreate OpenAPI `FreightRequest` schema
201 but incomplete dispatch	Partial payload	Review the returned `DispatchContainer` to confirm all expected moves, legs, stops, and freight were created

Symptom	Likely cause	What to check
Connection refused or DNS failure	Wrong host or CHC not reachable	For TTC paths, use `cloud.dev.api.trimblecloud.com` in dev; for direct CHC, confirm the customer’s public URL in CloudHub configuration — see CHC Installation
CHC installed but TTC cannot route requests	CHC not publicly reachable or wrong `oDataEndpoint`	Verify HTTPS is configured, firewall allows TTC traffic, and CloudHub configuration points to the public CHC URL
BuildInfo returns error or times out	CHC not running in IIS	Check IIS application pool status and Windows Event Viewer — see verify installation
Cities `$count` fails	Database connection issue	Verify `ConnectionStrings.Default` in `appsettings.json`; confirm encryption keys exist if the string is encrypted — see connection string encryption
500 Internal Server Error	Transient or downstream failure	Retry with exponential backoff; if persistent, contact support with the `requestId` from the error response
Documentation page not found locally	Stale dev server cache	Run `pnpm astro sync`, delete the `.astro` folder, and restart the dev server

If the issue persists after checking the items above, contact Trimble Transportation support. Gather the following before opening a case: