Wolt Drive API error handling

Managing both expected and unexpected errors is crucial when integrating with Wolt Drive APIs.

API relies on standard HTTP response codes to indicate the outcome of API requests. Status 5XX should be retried, while retrying any of the requests with 4XX status will result in the same response. Retries should follow a retry strategy with maximum 5 retries per request and, if possible, exponential back-off (increased time between retries).

A clear feedback loop for errors is needed to keep users informed of delivery unavailability or any mishaps. Additionally, error responses should be logged for further analysis.

Standard error response formats

400 Invalid payload

In the provided example, dropoff location is too far from the pickup location. Standard format applies to venueful and venueless endpoints. Webhook service and order modification endpoints may have different response formatting, detailed in their documentation.

See the list of error codes below.

{
  "error_code": "DROPOFF_OUTSIDE_OF_DELIVERY_AREA",
  "reason": "Dropoff location is outside of the delivery area",
  "details": "Delivery distance between pickup and dropoff (10711m) is longer than maximum allowed distance (8000m)"
}

401 Unauthorized

In the provided example, used merchant key does not allow access to merchant's resources.

{
  "detail": "Token not found for the given key and author"
}

404 Not found

In the provided example, venue ID does not exist in the system.

{
  "detail": "Not Found"
}

Additionally, shipment promise ID does not exist in the system.

{
  "error_code": "SHIPMENT_PROMISE_NOT_FOUND",
  "reason": "Shipment promise not found",
  "details": "Shipment Promise not found for the given id: {id}"
}

422 Unprocessable Entity

In the provided example, recipient phone number does not pass validation.

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "recipient", "phone_number"],
      "msg": "Value error, Impossible phone number: {phone_number}"
    }
  ]
}

500 Generic Internal Error

{
  "error_code": "GENERIC_INTERNAL_ERROR",
  "reason": "Internal server error",
  "details": ""
}

Error codes