Most integration problems can be narrowed down quickly.
Start with the HTTP status, environment, endpoint, and token. Then capture the response and X-Request-ID before changing the request.
401 Unauthorized
Check the environment
Sandbox: https://workspace-stage.connectuscorp.com/api/v2
Production: https://workspace.connectuscorp.com/api/v2
Make sure the matching Sandbox or Production Token is used.
Check whether the token changed
Only one token can be active. If a new token was generated in SSP, update your integration with the current value.
Also verify the header format exactly:
Authorization: Bearer YOUR_API_TOKEN
404 Not Found
For project and kit endpoints, a 404 can mean that the requested record does not exist or is not owned by the customer represented by the token.
- Do not reuse IDs copied from a different customer or environment.
- Retrieve IDs from the current environment before using them in a later request.
- Confirm you did not mix sandbox IDs with production IDs.
422 Validation failed
The Sales Order endpoint returns an errors object when request data fails validation. Treat field errors as actionable data and return them to your integration logs or operator.
{
"message": "Validation failed",
"errors": {
"customer_po_no": ["Customer PO No. is required."],
"items": ["At least one item is required."],
"ship_address.country": ["Country must be a 2-letter ISO code."]
}
}
A validation problem will usually keep failing until the request data is corrected. Automatic retry loops are not useful for this class of error.
500 Server / upstream error
A server-side failure can be temporary. Capture the response, request time, environment, endpoint, and X-Request-ID. If your application retries, use a controlled backoff and avoid rapidly sending the same write request many times.
The request succeeded but I cannot find my order
- Search using the exact customer_po_no you submitted.
- Check that you are searching in the same environment in which you created the order.
- Read the sales_order_number returned by the create request and retain it in your logs.
- Store the ConnectUs id returned by the Sales Order search results.
Available data is empty
An empty list is not automatically an API error. It can mean there is currently no matching data exposed to your account. Confirm the customer account and environment first; then confirm business configuration such as projects, kits, or inventory with your ConnectUs contact.
Token rotation broke the integration
This is expected if a new token was generated. Copy the current token from SSP, update the secret used by your integration, and retry a safe read request such as GET /client/projects.
What to capture before contacting support
- Environment: Sandbox or Production.
- Date and time of the request, including timezone.
- HTTP method and endpoint path.
- HTTP status code.
- X-Request-ID, if supplied.
- customer_po_no or Sales Order ID, when relevant.
- Response body with secrets removed.
Tokens are credentials. Redact the full token from screenshots, logs, chat messages, tickets, and email.