A batch is a collection of independent lookups, not an all-or-nothing delivery promise. Trace’s synchronous batch endpoint accepts up to 20 tracking numbers. Your application must inspect each result even when the HTTP request succeeds.
Mixed batches return HTTP 200 with successful and failed rows. An all-failed batch returns HTTP 503 with results. Code that discards the body on every non-2xx response loses the diagnostics needed to decide which work to retry.
Keep each request bounded
Send tracking_numbers as an array and provide a shared carrier only when it is correct for every item. Group by known carrier or omit the override when supported detection is appropriate. Break a large import into a controlled workflow rather than sending an oversized array.
Request body · placeholders are not live sample parcels
{
"tracking_numbers": ["PARCEL_ONE", "PARCEL_TWO"],
"carrier": "ups",
"allow_stale": false
}Inspect the rows before declaring success
Parse the response body and retain the top-level request ID. Classify every row with an error as failed and every successful row according to its freshness metadata. The helper below classifies a parsed batch result; it does not replace HTTP handling or input validation.
JavaScript · classify a validated batch response
function classifyBatch(body) {
if (!Array.isArray(body.results)) throw new Error("Missing batch results");
return body.results.map((result, index) => ({
index,
outcome: result.error ? "failed" : "succeeded",
code: result.error?.code ?? null,
status: result.error ? null : result.status,
stale: result.error ? false : result.stale === true,
}));
}Budget for submitted capacity and successful usage
A synchronous batch reserves capacity for the submitted items while it runs, then consumes monthly quota only for successful items. A failed item does not spend monthly lookup allowance. Cached and explicitly requested stale successes still count. That is why a batch containing 20 parcels is not priced as one successful lookup.
The per-minute request limit is separate from monthly lookup quota. Avoid firing a burst of concurrent batches from multiple workers just because each request contains fewer than 20 numbers. Coordinate the account’s request budget and inspect response headers.
Retry only the work you still need
Save completed results before planning another attempt. Retrying the whole batch can repeat successful work and consume more quota. For transient failures, schedule the failed subset with bounded backoff and honor Retry-After. For invalid input or authentication failures, correct the cause before retrying.
When a synchronous request does not fit your hosting deadline, use an asynchronous tracking job. That workflow returns a durable job identity and per-row result pages, so the customer’s web request does not have to wait for all carrier work.
Common questions
Does HTTP 200 mean every parcel was tracked?
No. A mixed batch can return 200. Inspect each result and failed_count before reporting completion to the caller.
References & next steps
Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.