Error codes and reasons
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. It is required to have a clear feedback loop and workflow when DoorDash rejects an API call.
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
- if the issue persists, let us know
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 Name | Error |
|---|---|
| pickup_external_business_id | missing pickup_external_business_id |
| substitution_preference | When substitution_preference is passed as \"substitute\", then substitute_item_ids cannot be null or empty |
| substitution_preference | The substitution_preference cannot be \"contact\" if customer communication is suppressed |
| item external_id | The following external ids were not found: [1234567890] |
| item external_id | Item: 123456 is suspended and not available |
| item weight | weight needs to be specified for item with external id 123456 |
| Dropoff Option - signature | Signature is set to required for contactless delivery |
| Dropoff Option - signature | Signature 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.