Sandbox and test carriers
The sandbox at https://sandbox-api.dollartraq.com behaves exactly like live: the same endpoints, fields, errors, headers and rate limiting. What differs is the data. Instead of real carriers it has a small set of test carriers, each built to produce one outcome your code needs to handle.
Sandbox requests are never counted against your monthly quota and are never billed. Every sandbox response has "livemode": false and a DT-Environment: sandbox header.
Test carriers#
Look these up by USDOT number (?dot_number=1000001) or MC number (?mc_number=MC1000001). They return the same result on every call.
| USDOT | MC | What you get | Score | Decision |
|---|---|---|---|---|
1000001 |
MC1000001 |
Approved, top grade | 94 (A) | approved |
1000002 |
MC1000002 |
Approved, one minor finding | 82 (B) | approved |
1000003 |
MC1000003 |
Review: safety findings | 66 (D) | review |
1000004 |
MC1000004 |
High risk: crash history | 48 (F) | high risk |
1000005 |
MC1000005 |
Rejected: knockout | 18 (F) | rejected |
1000006 |
MC1000006 |
Review: new authority, thin data | 72 (C) | review |
1000503 |
MC1000503 |
Always 503 scoring_unavailable, to test retries |
– | – |
| any other | any other | 404 carrier_not_found |
– | – |
The sandbox's model_version is dt-trust-v3.5-sandbox, so a sandbox result can always be told apart from a live one in your logs.
Testing errors#
Everything in Errors can be produced on the sandbox:
| To test | Do this |
|---|---|
| Carrier not found | Any USDOT number not in the table, such as 4242 |
| Scoring outage and retries | USDOT 1000503. It always answers 503 with Retry-After: 30 |
| Bad input | dot_number=12ab, or send both dot_number and mc_number |
| Missing or wrong key | Leave out the header, or send your dt_live_ key to the sandbox |
| Rate limit | Send more than 120 requests within a minute |
The monthly quota applies to live requests only, so monthly_quota_exceeded cannot be produced on the sandbox. Handle it the same way as rate_limit_exceeded, without retrying until the next month.
What the sandbox does not do#
- It does not know real carriers. A real USDOT number returns
404 carrier_not_foundon the sandbox. - Its scores do not change when the scoring model is updated. Live scores do; see Versioning.