Error codes: HTTP statuses returned by the Detrack API

Reference for every HTTP status code the Detrack API v2 returns, what causes each one, and how your integration should respond.

The Detrack API uses conventional HTTP status codes to signal success and failure. Any 2xx response indicates success. 4xx responses indicate a client error you can fix by changing the request. 5xx responses indicate a Detrack server problem.

Client errors

Status	Meaning	Common cause
400	Bad request	Malformed JSON in the request body.
401	Unauthorized	X-API-KEY header is missing or invalid.
403	Forbidden	The key is valid but does not have permission for the request.
404	Not found	The record (job, depot, route) does not exist.
422	Validation failed	Required fields are missing or field values are invalid.
429	Too many requests	Too many requests in a short period. See Rate limits.

Validation error response

When validation fails, the response body includes a code, message, and an errors array pointing at the fields that failed:

{
  "code": "validation_failed",
  "message": "Validation failed",
  "errors": [
    { "field": "do_number", "codes": ["cannot be blank"] }
  ]
}

Bulk endpoints (Create, Update, Delete) also return a per-record errors array so you can identify exactly which items in the request failed while the others succeeded.

Handling errors

• 401 / 403: check your API key and account permissions. Do not retry.
• 404: verify the do_number, date, and type you passed. Do not retry.
• 422: read the errors array, fix the request, and try again.
• 429: back off and retry with exponential backoff, respecting Retry-After if present. Consider using bulk endpoints.
• 5xx: retry with exponential backoff. Contact Detrack support if the error persists.