Skip to main content

Error codes and reasons

API: Drive

This doc covers the Drive API. If you're using the Drive (classic) API, see the reference guide for Drive (classic) errors.

Drive API uses standard HTTP response codes to indicate the success or failure of an API request.

The following code ranges apply to all endpoints:

  • 2xx - operation was a success
  • 4xx - operation failed due to a client error, trying again would result in same outcome
  • 5xx - operation failed due to temporary Doordash failure, please try again later

More specifically, the following codes have common meaning across endpoints:

  • 200 - everything is ok
  • 400 - the request was syntactically invalid and couldn't be processed
    • often caused by missing parameters, or parameters with wrong value types
  • 401 - authentication error
    • most likely cause is bad or expired JWT token meaning that Doordash was unable to securely verify identity of the caller
  • 403 - authorization error
    • identity was securely verified, but the supply identity doesn't permit the requested operation or data access
  • 404 - resource doesn't exist
    • this could be caused by either calling a wrong URL, or by looking up a delivery that doesn't exist
  • 409 - system state doesn't allow operation to proceed
    • most often caused by creating new delivery with duplicate ID, or trying to cancel delivery that isn't active
  • 422 - logical validation error
    • request was properly formatted but the operation isn't actually possible to execute
    • for example, requesting delivery outside of coverage area
  • 429 - too many requests
    • too many requests sent in short timespan, please wait and try again

Standard Error Format

When error is returned the following standard response format is used. Individual errors may include additional fields if needed, but all error responses are guaranteed to have at least these.

{
"code": "validation_error",
"message": "Validation Failed"
}

code is a machine readable enum, specific values are operation specific

message is a human readable explanation of the error in English, and is only included for debug purposes

Validation Errors

Validation errors (the 400s from the list above) have additional properties:

{
"code": "validation_error",
"message": "Validation Failed",
"field_errors": [
{
"field": "order_value",
"error": "Numeric value (100000000000) out of range of int (-2147483648 - 2147483647)"
}
]
}

field_errors is an array of all the validation errors encountered. Note that depending on the specific input it may not be possible to return all the validation errors.

Each validation error is represented by an object with two properties:

field - either the name of the field, name of the parameter, or body if no specific field can be attributed

error - human readable explanation of the error in English, and is only included for debug purposes

Logical Errors

Logical errors (for example requested delivery distance is too far) follow the standard error format. Optional additional properties and possible values of code are specific to each operation and described alongside those

Asynchronous Errors

Some operations can fail after the initial response was returned successfully. For example, a new delivery can fail after it was created if the payment didn't go through.

Asynchronous errors are represented as delivery statuses. To retrieve those, the client would need to request the latest delivery information and check the returned status there.