Rating Internals: Failures, Reconciliation, Limits

This staff-only article explains how the Tai TMS carrier rating works behind the scenes: how failures are classified as "not serviced" or "timeout", how a quoted total is reconciled against the itemized charges, which carriers have authentication errors suppressed, how repeated authentication failures switch an integration off, where retries do and do not happen, which carriers are skipped before rating, how direct-versus-interline transit data is carried and used, where rate-intelligence data comes from, and a set of carrier-specific rating rules.

Overview

The Tai TMS rates a shipment in two layers. The TMS rating engine chooses which tariff lanes (carrier connections) to ask, then, for carrier-integration lanes, hands one carrier-agnostic request to the carrier rating service, which dispatches it to the selected carrier or rate provider and returns a normalized result split into successful quotes and failed quotes. The service maps 126 carrier and provider types to about 109 distinct carrier implementations (several carriers share one implementation, for example Con-way is rated through the XPO implementation and Midwest Motor Express through AAA Cooper); a few sources (the SMC and Truckmate tariff engines, MARS, most DAT lookups, and Loadsmart) are rated inside the TMS instead. This article covers what support and engineering staff need when diagnosing rating problems: how failures are labeled, how totals are reconciled, the deliberate suppression of authentication errors for two carriers, the authentication back-off, the narrow places where a call is repeated, the not-serviced memory and Smart Quote that narrow the carriers asked, the transit-type data, and recent carrier-specific rules.

How it works

1. The TMS picks the lanes. For a rating request the engine collects the tariff lanes that apply to the customer, applies carrier rules, and then pre-filters carriers it already knows it cannot use (see "Which carriers are asked").
2. The request is normalized and sent live. For each carrier-integration lane the TMS maps the shipment into one carrier-agnostic request (with the integration's credentials and settings, and a time limit), and the carrier rating service translates it into the specific carrier's request format, calls the carrier live, and translates the reply back into normalized quotes.
3. A logging wrapper catches every failure. The wrapper around the carrier call catches every possible error and turns it into a failed quote carrying an error message plus serviced, authentication, and timeout flags. After the call, a post-processing pass finalizes the timeout and "not serviced" labels and clears the expiration date when the Dynamic Pricing setting is off. The result is always returned as successful quotes plus failed quotes.
4. The TMS builds the quote records. Back in the TMS, each normalized quote becomes a rate: freight, fuel, guaranteed and accessorial lines are built, accessorials are matched against the integration's accessorial map, and the carrier's total is reconciled against the lines the TMS built. Carrier-reported transit type is applied, results are sorted, "not serviced" answers are recorded, and authentication failures are counted.

Business rules & limits

Failure classification

• "Not serviced" is determined in three layers. First, some carrier adapters decide from carrier-specific phrases and raise a definitive "lane not serviced" signal (12 carriers' adapters check their own carrier-specific phrases: AAA Cooper, EDI Express, Ward, Southeastern Freight Lines, Daylight Transport, Averitt, Dayton Freight, A. Duie Pyle, Pitt Ohio, FedEx, Dot Line and Vision Express). Second, any carrier service can raise the same signal directly. Third, as a fallback, for any failed result where "serviced" was not set, the error message is checked against a curated list of 28 "not serviced / no rates / out of service area" entries (27 distinct phrases; "No rates returned for carrier" is listed twice), for example "requested service is not supported," "out of service area," "does not service," "Out Of EDI's service area," "AT LEAST ONE POINT MUST BE SERVICED," and "Provided zips are not within the service area." The match is a case-insensitive "contains" check, so a short phrase such as "Service not available" matches any message that includes it. The same 28-entry list is used both by the carrier rating service and by the TMS-side rating wrapper (used for DAT and Loadsmart). A carrier that returns a new, unlisted wording is treated as a generic failure, not flagged as not serviced, until the phrase is added.

• "Timeout" is determined two ways. A canceled or timed-out call is labeled "Operation was timed out." In the post-processing pass, any failed result not already flagged as a timeout has its error message matched (case-insensitive) against "timeout," "time out," "timedout," and "timed out"; a match flags the result as a timeout. The time limit comes from the integration source's Rating Timeout setting, defaults to 15 seconds when the setting is blank, and must fall within 15 to 75 seconds: a value outside that window is rejected by the carrier rating service as an invalid request. For the DAT and Loadsmart lookups that are rated inside the TMS, the generic timeout setting is effectively ignored when it is a valid number (the 15-second default stays), because of a known inverted check in the setting's parser; a non-numeric value sets the limit to zero. The timeout flag is set on the carrier service's failed result; for carrier-integration quotes the TMS's own quote record carries the error text (for example "Operation was timed out.") rather than that flag.

• Authentication errors are deliberately suppressed for two carriers. When a rating call fails authentication, the result is normally flagged as an authentication error. For ConWay (XPO) and Southeastern Freight Lines this flag is forced back to off, so those two carriers never report an authentication error even on a genuine auth failure, and as a result they also never add to the rating back-off count described below. When troubleshooting "why did this carrier return no quote" for either of them, do not rely on the authentication-error flag; check the error message text instead.

• An empty result reads as "No quotes returned!" Any carrier adapter that returns an empty list, or whose response shape is not recognized, surfaces as a failed quote with the message "No quotes returned!" rather than as a parse error. A carrier reply that drifts from the expected shape therefore looks like "no quotes" until the adapter is fixed.

• The carrier rating service never throws. Failures are not surfaced as exceptions; they are returned as failed results with the error text and the serviced, authentication, and timeout flags set, and the TMS converts any exception it does see into a failed quote as well. Callers must inspect the failed-results list and those flags rather than relying on an error status. This is why one failed carrier never breaks the overall request. The one edge is a carrier type that has no entry in the carrier mapping: that request fails as a server error before the wrapper runs.

• Known edge case when a carrier returns both successes and a failure. In a specific case where a carrier returns some successful rates and also a failure in the same response, the failure record is not attached to the returned result (the failed result is added to a throwaway copy of the list). If a carrier appears to have partially failed but no failure entry shows up, this edge case is the likely reason.

Totals, accessorials and expiration

• A quoted total is reconciled against the charges the TMS built, within 0.5%. This check runs in the TMS after the carrier's reply has been translated; it is not performed inside the carrier rating service. The TMS adds up the freight, fuel and accessorial lines it built and compares the sum with the carrier's quoted total. If the two are within 0.5%, the quote passes as is. If they differ by more than 0.5%, the TMS adds a "Miscellaneous Charge" accessorial (code MISC) equal to the exact difference (quoted total minus built total) and re-checks; if the totals still do not reconcile, the quote fails with "Processed total did not match quote from API." A built total of $0 fails with "Processed total from API returned $0," both totals at $0 fails with "Processed total and quoted total from API both returned $0," and a quoted total of $0 on its own ends in the mismatch failure. The same check is applied to DAT market-rate estimates.

• Accessorials are matched before the call and checked after it. Before calling the carrier, each requested accessorial must have an entry in the integration source's accessorial map; a requested accessorial with no entry fails that carrier up front with "Mapped Accessorial not found for carrier: (Id: n)". Only entries whose direction allows sending are actually sent to the carrier (incoming-only entries are not sent), and accessorials mapped as "bypass external rating" are priced by the TMS itself and are not sent. After the reply, a requested accessorial that the carrier did not price fails the quote with "Accessorial Not Returned from Carrier," except accessorials waived on the tariff, which appear as zero-dollar lines. For Roadrunner and Con-way (XPO), a shipment of 500 lb or less automatically adds the single-shipment fee accessorial unless the integration's Ignore Single Shipment Fee setting is true.

• Accessorials can be edited and re-rated on the new Shipment Rating page (TMS-24178). With the "New Rating Page - Inline Accessorial Editing And Re-Rate" feature flag on, the Shipment Info card on the rating page gets an Add Accessorial picker (suggestions grouped by Shipment, Pickup and Delivery) and a remove icon on each accessorial. It follows the same rules as shipment details: the section is read-only once a linehaul charge line has a Created invoice or bill, and the remove icon is hidden on an accessorial whose charge line is past Has Variance. Changing an accessorial cancels any rating request in flight, clears the quotes, and blocks quote selection until the user clicks Re-Rate, which reruns rating with the current accessorials and reapplies the filters. When every carrier errors, typically because no carrier's tariff prices the added accessorial ("Accessorial Not Returned from Carrier" or the missing-mapping failure above), the page shows "No Rates Found" with a Show Errors button; a request that fails outright shows an error with Retry. With the flag off, accessorials cannot be changed on the rating page.

• Missing charges default to zero. A charge category a carrier does not return reads as zero rather than as an error, and every charge is rounded to two decimals when read, so a mis-mapped fuel surcharge looks like "no fuel," not a failure. Keep this in mind when a total looks right but a component is unexpectedly zero.

• The Dynamic Pricing setting controls whether a quote shows an expiration date. The integration source's Dynamic Pricing setting is read after every rating. If it is blank or absent, or set to true, the expiration date the carrier supplied is kept. If it is set to anything else (false, or any non-blank text that is not literally true, such as a typo), the expiration date is cleared on every successful quote from that source. DAT and Loadsmart quotes, which are built in the TMS, keep the date when the value cannot be read. XPO (Con-way) is the one carrier whose adapter reads the setting itself: with Dynamic Pricing on, which is the default when the setting is unset, the XPO adapter stamps the quote's expiration as 11:59 PM Eastern on the day of the quote.

• Request-echo validation for four carrier adapters. The FedEx REST (standard and express) and Averitt (updated and dynamic) adapters compare the origin ZIP, destination ZIP, freight class, weight and handling-unit count the carrier echoed back with what was requested (blank echoed values are ignored). Any difference fails the quote with "You requested a rate for [origin, destination, class, weight], but returned mismatched values: ... Please try again."

Authentication back-off, retries and timeouts

• Repeated authentication failures switch an integration off for rating. Each time a rating request returns an authentication error for an integration source, the TMS adds one to that source's failure count (one count per rating request, however many lanes failed). The source is switched into an Authentication Error state when a failure is recorded while the count is already 4, so the fifth failure flips it. From then on every lane that uses that source fails immediately without calling the carrier, with the message "The Integrationsource has invalid credentials!". The count is cleared and the state lifted when the integration source is edited and re-saved (typically after fixing the credentials). A daily job (scheduled for 4:00 AM) also sets the failure counts back to zero, but only for sources that are not yet in the Authentication Error state, so failures only accumulate within a day and the job never lifts the error state. A successful rating call does not clear the count by itself. A "this vendor suddenly stopped returning anything" symptom often traces to this back-off.

• Other integrations use a different threshold. Integrations that count failures through the per-source helper (for example DAT, CargoChief pricing, EPay, CarrierConnect and several carrier-onboarding and tracking integrations) switch to the Authentication Error state only when the count exceeds an allowed limit: five by default, adjustable per integration with an Allowed Failure Count setting, so with the default it is the sixth failure that trips it. The same reset rules apply (re-saving the source, or the daily counter reset for sources not yet switched off).

• There is no automatic retry of a failed carrier, with narrow exceptions. The carrier rating service and its shared HTTP clients do not retry, back off or cache; a carrier failure is returned on the first attempt, and there is no retry or back-off setting. The exceptions are: (1) Southeastern Freight Lines quote details are polled: for each quote link the service re-requests immediately, up to 11 attempts in total with no pause between them, while the reply reports an error or error text, stops at once if the error says an automated response cannot be generated, and keeps the first clean reply; if the attempts run out (or the reply carries no error flag) it waits 2 seconds and keeps the last reply, with no growing delay. (2) DAT truckload and market-rate lookups log in again once and repeat the request if the first reply is a service error. (3) Smart Quote re-run: if predictive carrier selection is on for a request and the first pass returns no successful quote (every result failed, or none), the rating engine repeats lane selection and rating one more time. A carrier reply that mentions throttling or a limit is not retried; the TMS shows the carrier's message, or "Throttling exception please wait a couple of minutes before retrying" when the reply is a web page.

Which carriers are asked

• "Not serviced" answers are remembered for 45 days. After each rating run the TMS records every carrier (by carrier code) that came back not serviced for the pickup and delivery ZIP-code pair, except nine brokerage-style integration types whose answers vary by account (BlueGrace, Echo Global Logistics, ExFreight, World Wide Express, GlobalTranz, Priority 1, Unishippers, DLS Worldwide and Quad Express). On later requests for the same ZIP pair the pre-rating filter drops lanes whose carrier code is on that list, so the carrier is not called at all. This remembered list is the filter used when the broker has no SMC/Truckmate CarrierConnect credential on file (or CarrierConnect is unavailable); when a CarrierConnect credential is in use, CarrierConnect's own service data decides instead, and if every lane is set to Service Type "All" nothing is filtered. A cleanup job deletes entries older than 45 days. Because a phrase-matched "not serviced" label is recorded the same way as a definitive one, a broad phrase match can keep a carrier out of that ZIP pair's quotes until the entry expires. This is memory of availability only; prices are never cached or reused, and a stale or unexpected price is not a caching artifact.

• Smart Quote narrows LTL carriers using recent history. When predictive rating is on, the customer was created more than 90 days ago, the lane has more than 8 eligible tariff profiles, and the prediction finds more than 2 carriers, the lanes are narrowed to the predicted carriers plus any tariff whose effective date is within the last 90 days. The predictions are up to six carriers scored from the last 90 days of shipments for that customer and, with lower weight, for the broker's accounting organization on the same three-digit ZIP lane. Otherwise (a new customer, or too few carriers) the full set is rated.

• Rate intelligence comes from predictive market-rate providers. Beyond published carrier tariffs, the TMS can draw estimates from market-rate sources such as Greenscreens, DAT, CargoChief lane pricing and Loadsmart. These estimate a likely market or spot price for a lane rather than quoting a single carrier's tariff. For DAT's market view, the spot estimate is computed as the estimated linehaul rate plus the average fuel surcharge rate, multiplied by miles.

Direct versus interline transit type

• Carriers can report direct-versus-interline service. 22 LTL rate converters (about 18 carriers: AAA Cooper, ABF, Best Overnite, CoyoteGO LTL, CTII, Dayton Freight, Estes (EXLA), FedEx, Magnum, Mountain Valley, Numark, Old Dominion, Pitt Ohio, RIST, R+L, Southeastern Freight Lines, Saia and Ward) populate a transit-service-type value on each successful quote, derived from the carrier's own interline or lane data, plus the interline/partner carrier's name when the lane is not direct. The values are Direct, Indirect Origin, Indirect Destination, Indirect, Partner, Does Not Service and Unknown. Converters whose carriers return no such data leave it empty, which reads as Unknown. Carrier rules differ: for example Southeastern Freight Lines treats a partner-interline point as not direct, AAA Cooper's blank interline flag means Direct and "X" means Indirect, a Magnum reply that is indirect at only one known end becomes Indirect Origin or Indirect Destination, and Pitt Ohio's rate reply carries no routing data, so after a successful rate the TMS asks Pitt Ohio's transit-time service and quietly leaves the quote Unknown if that call fails.

• Two feature flags control how the TMS uses it. With the "Carrier API Transit Type" flag on (TMS-23823), a Direct, Indirect Origin, Indirect Destination, Indirect or Partner value reported by the carrier overrides the origin and destination service type (direct or indirect at each end) that was derived from CarrierConnect transit data; Unknown or no value leaves the existing value alone. Those two codes drive the "Indirect Origin," "Indirect Destination" and "Indirect" labels next to the transit days in the rates list and, since TMS-24811, on the rate cards of the new Shipment Rating page (a direct quote shows no label). On both, a not-serviced code shows a warning icon with "Lane is not serviced by this carrier." and a not-found code shows "Not Found" with the quote's error message as a tooltip. The rate-card label itself is not behind a feature flag; only the carrier-reported override above is. The partner carrier is written to the rating log. With the "Carrier API Transit Type Filtering" flag on (TMS-23826), a quote is dropped when the tariff lane's Service Type setting is anything other than All and the carrier's reported value is not one that setting accepts: Direct accepts only Direct, Indirect Origin and Indirect Destination accept only themselves, Indirect accepts Indirect, Indirect Origin, Indirect Destination and Partner, All Serviced accepts anything except Does Not Service, and a carrier-reported Does Not Service is rejected by every setting other than All. An Unknown or absent value never drops a quote. If every quote from a lane is dropped, the lane returns nothing.

Carrier-specific rating rules

• A. Duie Pyle over-dimension (TMS-23539). The carrier assesses one over-dimension measurement per shipment, so only the single piece with the highest tier is sent. Each piece (converted to feet) is tiered: length of 20 ft or more, 16 ft or more, or 12 ft or more are the top three tiers; length or width of 10 ft or more, 8 ft or more, or 6.5 ft or more are the next three; and both length and width of 6 ft or more is a tier equal to the 8-ft tier. The highest tier wins, ties go to the longest length, and its length and width are sent truncated to one decimal (each only if that dimension qualified). The generic over-length accessorial no longer sets these values. Carrier errors show as " (A. Duie Pyle error )" unless the code is blank or 0.
• Priority 1 discount lines (TMS-19612). Discount charges are found by priority: charges whose code is one of the known discount codes (when they sum to a non-zero amount), else charges whose code contains "DISCOUNT," else (for carriers other than FXFE and FXNL) charges whose description contains "DISCOUNT." The quote's discount is the absolute value of those amounts, freight is reduced by it when freight is at least as large, and those lines no longer appear as accessorial charge lines.
• Xpress Global negative lines (TMS-19712). Any charge line with a negative amount is treated as a discount: the discount is the absolute value of the negatives, freight (lines coded L or A) is reduced by it when freight is at least as large, and the negative lines no longer show as a negative miscellaneous charge.
• Southwestern Motor V2 (TMS-24236). The rate block may arrive under either of two names and the adapter reads whichever is present; with neither, the quote reads as "No quotes returned!". Freight is the carrier's freight minus its discount, and the discount is reported separately. Any status code other than the success code fails the quote with the carrier's message.
• Bungii (TMS-24295, TMS-23560). There is no longer a total-weight guardrail: one driver up to 125 lb, two drivers above 125 and up to 250 lb, and no driver count above 250 lb (left unset). A service plan is sent when either the Service Plan Id or the Secondary Service Plan Id is configured. The customer id setting is Bungii Customer Id; when it is missing the quote fails with "Parameter BungiiCustomerId is required".
• NSure (TMS-24788). The insured party (name, address, phone) is the shipment's end customer, not the integration's bill-to; the shipment id is sent as the BOL number, invoice number and reference. A request with no deductible uses the integration's Default Deductible setting, else $1,000.
• RIST Transport updated (TMS-19462). Pickup accessorials become services on the origin stop and delivery accessorials services on the destination stop (Inside, Liftgate, Limited Access, Residential, Sort, Straight Truck, Notify, School, Airport); accessorials that match none of these are silently dropped.
• Dot Line (TMS-19453). A rate reply that includes a success marker ahead of the response code now rates normally; it previously failed with "Unable to rate".
• FedEx routes to the FedEx LTL Freight platform when the integration is flagged as FedEx Freight. The FedEx rating service checks a FedEx Freight setting on the integration source. When it is on, the quote is sent to the FedEx LTL Freight platform (freight-specific production and stage endpoints) and the FedEx authentication call requests the freight scope; when it is off, the legacy FedEx freight-rates endpoint is used. So a FedEx account failing to return LTL quotes can be a case of the FedEx Freight setting not matching the account type rather than a credential problem.