A screenshot saying “tracking failed” is rarely enough to locate an intermittent problem. A useful incident record links the application operation to the API request, preserves the error category and records when it happened.
More logging is not automatically better. Authorization headers, customer addresses and full parcel histories can turn routine diagnostics into a sensitive data store. Start with an allowlist of operational fields and retain private payloads only when necessary under your own access policy.
Keep a small, consistent diagnostic envelope
Record your operation ID, the API’s request ID when supplied, the endpoint, HTTP status, structured error code and elapsed time. Add whether the operation was a sandbox, direct, cached or asynchronous workflow when that information is actually known. Do not infer a live result from a generic success flag.
The SDK TraceError preserves status, code, request ID and retry information. A transport failure may have no API request ID because no response arrived. Preserve your local operation ID in that case instead of inventing an upstream identity.
Use an allowlist rather than redacting an arbitrary object
The helper below constructs a diagnostic record from selected values. It deliberately excludes request headers and response bodies. In your application, validate and bound string lengths and route records through your normal protected logging system.
JavaScript · controlled diagnostic shape
function trackingDiagnostic({ operationId, requestId, status, code, durationMs }) {
return {
operation_id: operationId,
request_id: requestId ?? null,
http_status: Number.isInteger(status) ? status : null,
error_code: code ?? null,
duration_ms: Math.max(0, Math.round(durationMs)),
};
}Route the investigation by the failure category
Authentication failures call for credential configuration checks. Rate limits call for coordinated admission and Retry-After handling. Monthly quota exhaustion calls for a plan or reset decision. Source unavailability calls for checking acquisition evidence and an honest customer fallback.
A timeout in your host can occur before the API’s own attempt finishes. Compare your application deadline with the client timeout and any retries. Switching to a durable async job can be more appropriate than repeatedly increasing a customer-facing request timeout.
Prepare a useful support report without a secret dump
Include the time range and timezone, affected endpoint, request IDs, error codes, whether the problem is reproducible and the impact on your application. Share customer tracking details only through an appropriate authorized support channel when they are necessary.
Before deploying a logging change, test that an exception cannot serialize the API key, authorization header or full request object. Check background workers as well as web handlers; different libraries can attach sensitive request configuration to their error objects.
Common questions
Should I paste my API key into a support ticket?
No. Request IDs, timestamps and error codes are the starting point. Keep API keys in your secret store and rotate one if it was exposed.
References & next steps
Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.