Errors

The API uses HTTP status codes to say whether a request worked, and returns every error in the same shape:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_dot_number",
    "message": "dot_number must be a USDOT number: 1 to 8 digits.",
    "param": "dot_number",
    "doc_url": "https://developers.dollartraq.com/docs/errors#invalid_dot_number",
    "request_id": "req_8f3k2m9x1q7w4e6r0t5y2u8i"
  }
}

• type is the broad kind of error. Branch on it for the general case.
• code is the specific reason. Branch on it when you handle a case differently.
• message is written for a developer and may change. Do not parse it.
• param names the parameter at fault, when there is one.
• request_id identifies the request. Quote it when you contact support.

Types#

Type	Status	Means	Retry?
invalid_request_error	400, 404, 405	The request was wrong	No. Fix the request
authentication_error	401	The API key was missing or not accepted	No. Fix the key
permission_error	403	The key is valid but the account cannot use the API	No
not_found_error	404	No carrier matches	No
rate_limit_error	429	Too many requests, or the monthly quota is used up	After Retry-After
api_error	500, 503	Something failed on DollarTraq's side	Yes, with backoff

Errors never count against your monthly quota.

Codes#

parameter_missing#

Neither dot_number nor mc_number was given. Send exactly one.

parameter_conflict#

Both dot_number and mc_number were given. Send exactly one.

invalid_dot_number#

dot_number is not 1 to 8 digits. USDOT 1234567 is accepted; letters elsewhere are not.

invalid_mc_number#

mc_number is not a docket number. MC123456, MC-123456 and 123456 are all accepted.

carrier_not_found#

No carrier with that USDOT or MC number is in the FMCSA data. Check the number with the carrier. On the sandbox, only the test carriers exist.

missing_api_key#

No Authorization: Bearer header was sent.

invalid_api_key#

The key is malformed, or no such key exists. Check for missing characters or extra spaces.

wrong_environment_key#

A dt_test_ key was sent to live, or a dt_live_ key to the sandbox. See Authentication.

revoked_api_key#

The key has been revoked. Use another key, or ask for a new one.

account_suspended#

API access for your account is paused. Contact DollarTraq.

rate_limit_exceeded#

More requests than your per-minute limit. Wait the number of seconds in Retry-After, then retry. See Rate limits.

monthly_quota_exceeded#

Your account has used its live requests for the month. Requests are refused until the quota resets on the 1st (UTC), or until DollarTraq raises it. Do not retry.

scoring_unavailable#

The score could not be calculated just now. Retry with exponential backoff, starting from Retry-After. If it persists for more than a few minutes, contact DollarTraq with the request_id.

internal_error#

An unexpected failure on DollarTraq's side. It has been logged. Retry with backoff; if it persists, contact DollarTraq with the request_id.

route_not_found#

No endpoint at that path. Check it against the API reference.

method_not_allowed#

The endpoint does not accept that HTTP method. All current endpoints use GET.

unknown_host#

The request reached DollarTraq on a host that does not serve the API. Use https://api.dollartraq.com or https://sandbox-api.dollartraq.com.