> ## Documentation Index
> Fetch the complete documentation index at: https://detrack.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/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:

```json theme={null}
{
  "code": "validation_failed",
  "message": "Validation failed",
  "errors": [
    { "field": "do_number", "codes": ["cannot be blank"] }
  ]
}
```

Bulk endpoints ([Create](/api-reference/jobs/bulk-create), [Update](/api-reference/jobs/bulk-update), [Delete](/api-reference/jobs/bulk-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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.