Skip to main content
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.

​
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).