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

# Response Codes

> HTTP status codes returned by the Alvys Public API — 2XX success, 4XX client errors, and 5XX server errors — with descriptions of each error code.

All API requests will respond with an appropriate HTTP status code. Your API client should handle each response class differently:

* **2XX** Successful responses
* **4XX** Client error responses indicate an issue with the request, such as missing parameters or invalid value. Modify the request before retrying.
* **5XX** Server error responses indicate a temporary issue on Alvys' side. Retry the request after some time. *If issues persist, please reach out to support for further assistance.*

## Error Codes

Alvys uses conventional HTTP response codes to indicate the success or failure of an API request. Below is a table of error codes to help you debug. The error response body may include an error message, but avoid hard-coding against specific messages, as Alvys reserves the right to change the error message without auto-incrementing the API version. Only use error messages for debugging purposes.

| Status Code | Description                                                                                                                                                                                                                                                                                                                       |
| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | **Bad Request** - General client error, possibly malformed data. Common error messages include: "Configuration limit exceeded" (e.g., system limits on creating more objects like users, drivers, and documents). Contact Support to request increases.                                                                           |
| 401         | **Unauthenticated** - The access token is missing or invalid. A mistyped or unknown path does **not** produce 401.                                                                                                                                                                                                                |
| 403         | **Permission Denied** - You do not have access to the requested resource.                                                                                                                                                                                                                                                         |
| 404         | **Not Found** - The request path does not match a published endpoint, or a path parameter does not match a resource (for example, `id` in `/drivers/\{id}`). A well-formed list or search that matches no records is **not** a 404 — see [No results is not an error](#no-results-is-not-an-error).                               |
| 405         | **Method Not Allowed** - The API endpoint does not accept that HTTP method.                                                                                                                                                                                                                                                       |
| 415         | **Unsupported Media Type** - The request's `Content-Type` is not supported by this endpoint. Only `application/json` and `application/x-www-form-urlencoded` are accepted.                                                                                                                                                        |
| 429         | **Too Many Requests** - The client has reached or exceeded a rate limit, a usage limit, or the server is overloaded. See [Rate Limits](/en/api/guides/rate-limits) for suggestions on retry patterns.                                                                                                                             |
| 5XX         | **Internal Server Errors** - something went wrong with Alvys' servers. These responses are likely momentary errors (e.g., temporary unavailability), and as a result, requests should be retried using exponential backoff. Note that the body of these responses follows the `application/problem+json` (ProblemDetails) format. |

## No results is not an error

List and search endpoints return **200 OK** with an empty collection when a well-formed query matches no records. Treat an empty `Items` array (or an empty list) as a successful empty result — not as a missing route, missing credential scope, or missing resource.

* **Paged search / list** — Response shape stays the same. `Items` is `[]`, and paging fields (`Page`, `PageSize`, `Total`) still reflect the request and the query's match count. Do not branch on `404` to mean "nothing matched."
* **Document lists** — When the parent resource exists but has no attachments, the endpoint returns **200** with `[]`. **404** still means the parent id is missing or not visible to your credential.

This applies across carriers, customers, drivers, fuel, invoices, loads, locations, maintenance, tolls, trailers, trips, trucks, users, and visibility outbound errors (including the related document-list routes).