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

The table below lists the possible field errors that are re-used across endpoints where the field is relevant

Field NameError
pickup_external_business_idmissing pickup_external_business_id
substitution_preferenceWhen substitution_preference is passed as \"substitute\", then substitute_item_ids cannot be null or empty
substitution_preferenceThe substitution_preference cannot be \"contact\" if customer communication is suppressed
item external_idThe following external ids were not found: [1234567890]
item external_idItem: 123456 is suspended and not available
item weightweight needs to be specified for item with external id 123456
Dropoff Option - signatureSignature is set to required for contactless delivery
Dropoff Option - signatureSignature is set to not required for alcohol order

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.