Error Handling
Learn how to handle and recover from errors received from the HopDrive API.
HopDrive uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a pickup address was invalid, etc.). Codes in the 5xx range indicate an error with HopDrive's servers (these are rare).
Some 4xx errors that could be handled programmatically (e.g., a pickup address was invalid) include an error code that briefly explains the error reported.
Your HopDrive integration might have to deal with errors like these at some point when making requests to the HopDrive API. These errors fall into three major categories:
- Content error — Invalid content in the API request.
- Network error — Intermittent communication problems between client and server.
- Server error — A problem on HopDrive servers.
The right approach and idempotency semantics to use for handling errors depend on the type of error being handled.
The HopDrive API applies idempotency for all GET and DELETE requests. See the idempotancy documentation for more information.
Content error
Content errors are the result of the contents of an API request being invalid and return an HTTP response with a 4xx error code. For example, the API servers might return a 401 if an invalid API key was provided, or a 400 if a required parameter was missing. Integrations should correct the original request, and try again. Depending on the type of user error (e.g., an invalid pickup address), it may be possible to handle the problem programmatically. In these cases, include a code field to help an integration react appropriately. See error codes for more details.
For a POST operation using an idempotency key, as long as an API method began execution, HopDrive's API servers will cache the results of the request regardless of what they were. A request that returns a 400 sends back the same 400 if followed by a new request with the same idempotency key. Generate a fresh idempotency key when modifying the original request to get a successful result. This operation does contain some caveats. For example, a request that's rate limited with a 429 can produce a different result with the same idempotency key because rate limiters run before the API's idempotency layer. The same goes for a 401 that omitted an API key, or most 400s that sent invalid parameters. Even so, the safest strategy where 4xx errors are concerned is to always generate a new idempotency key.
Network error
Network errors are the result of connectivity problems between client and server and return low-level errors like socket or timeout exceptions. For example, a client might time out while trying to read from HopDrive's servers, or an API response might never be received because a connection terminates prematurely. A network error wouldn't necessarily have otherwise been a successful request—it can also be another type of error that's been cloaked by an intermittent problem.
Server error
Server errors are the result of a problem with HopDrive's servers and return an HTTP response with a 5xx error code. These errors are the most difficult to handle and we work to make them as rare as possible—but integrations should be able to handle them when they do arise.
You should treat the result of a 500 request as indeterminate. The most likely time to observe one is during a production incident, and generally during such an incident's remediation.
Treat requests that return 500 errors as indeterminate. Ideal results are not guaranteed.
HTTP Status Codes
The following are HTTP Status Codes returned by the HopDrive API with a brief description of it's general meaning.
200 - OK
Everything worked as expected.
400 - Bad Request
The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized
No valid API key provided.
402 - Request Failed
The parameters were valid but the request failed.
403 - Forbidden
The API key doesn't have permissions to perform the request.
404 - Not Found
The requested resource doesn't exist.
500, 502, 503, 504 - Server Errors
Something went wrong on HopDrive's end. (These are rare.)
Error Types
In addition to HTTP Status Codes the response object will contain one of the following error types which describe the type of error returned.
authentication_error
Failure to properly authenticate yourself in the request.
invalid_request_error
Invalid request errors arise when your request has invalid parameters.
validation_error
Errors triggered by our client-side libraries when failing to validate fields (e.g., when a pickup address is invalid).
api_error
API errors cover any other type of problem (e.g., a temporary problem with HopDrive's servers), and are extremely uncommon.
Error Responses
When errors occur, in addition to the HTTP Status Codes returned, HopDrive will provide a response object that further describes the error(s) that occurred. Because at times multiple errors may occur, the response will always come back in the form of an array of error objects.
Examples
The following JSON objects represent example error responses for various scenarios.
Authentication Error
For secure endpoints a valid authentication Bearer token must be provided with the correct authorization scope to perform the steps required for API to complete it's work.
[
{
"type":"authentication_error",
"code":"missing_scope",
"message":"A scope required to perform the operation is not present in the provided authentication token.",
"doc_url":"http://api.hopdrive.com/docs/error-codes#missing_scope"
}
]
Invalid Request Error
When an API endpoint has specific input parameter requirements that are not met, this error type will be returned to indicate what is wrong.
[
{
"type":"invalid_request_error",
"code":"pickup_location_required",
"message":"A pickup location object is required but was not found in the request.",
"doc_url":"http://api.hopdrive.com/docs/error-codes#pickup_location_required"
}
]
Validation Error
This type of error will only be retuned along with an HTTP Status Code of 4xx. It should serve to provide more context to what might be wrong with the data provided in the request object payload.
[
{
"type":"validation_error",
"code":"address_invalid",
"message":"The address provided for the pickup location is not valid and cannot be used to schedule a vehicle move.",
"doc_url":"http://api.hopdrive.com/docs/error-codes#address_invalid"
},
{
"type":"validation_error",
"code":"address_invalid",
"message":"The address provided for the delivery location is not valid and cannot be used to schedule a vehicle move.",
"doc_url":"http://api.hopdrive.com/docs/error-codes#address_invalid"
}
]
API Error
This type of error will only be retuned along with an HTTP Status Code of 5xx. It should serve to provide more context to what might be wrong on HopDrive's end.
[
{
"type":"api_error",
"code":"internal_server_error",
"message":"Database is temporarily offline.",
"doc_url":"http://api.hopdrive.com/docs/error-codes#internal_server_error"
}
]