Detailed error spec
Overview​
The Detailed Error Spec standardizes how providers send order cancellation reasons to DoorDash. It ensures that a clear failure reason is included with all confirmed order cancellations. This enables DoorDash to trigger corrective actions like menu refreshes, item suspensions, or store deactivations, ultimately reducing cancellations and improving integration quality.
Why​
- Impact: Without actionable data, DoorDash can’t diagnose or fix the root causes behind order cancellations, causing a poor experience for our mutual customers.
- Opportunity: Integrated merchants will benefit from higher reliability and fewer missed orders once error reporting becomes standardized.
- Outcome: Providers who comply (<15% “Other” and <15% Null failure reasons) will see lower cancellations, higher uptime, and improved merchant satisfaction.
How​
Providers must:
- Send raw failure reasons with all confirmed cancellations.
- Meet thresholds:
- fewer than 15% of confirmed cancellations are returned with null failure reasons
- fewer than 15% of confirmed errors are vague/inactionable, which falls in the “other” bucket outlined below.
Required Error Spec Buckets​
Store Closed Failure Reasons​
| Error bucket | Error description | Example |
|---|---|---|
| General Store Closed | This includes all generic failure reasons indicating the store is closed. | Store is closed on 2025-10-04T21:00:59-05:00 |
| Early Store Closure | Happens when the store closes early for the day or is preparing to be closed for the day so the order cannot be prepared before closure. | Store is either currently closed or your order cannot be prepared prior to close. |
| Temp Closed | The store is marked as temporarily closed for reasons such as: renovations, weather issues, etc. | Store Unavailable - Closed or Remodel |
Store Open but Unavailable for POS Orders Failure Reasons​
| Error bucket | Error description | Example |
|---|---|---|
| Connectivity Issues | When DoorDash & POS are having trouble connecting and/or the store is having connection issues. | Store Unavailable - Connectivity Issue |
| Timeout | When the order is placed but Px does not send an order confirmation within the 5 min timeframe. Generally indicated by a null failure reason or with "timeout". | timeout |
| Capacity Throttling | The store has hit capacity for how many orders it can handle. | [Store Name] is experiencing high order volume and cannot prepare your order for [order placed time] |
| POS Offline | The POS is offline — this is a general closed reason because it could reference connectivity issues, planned store closures, etc. | POS Exception - Store is offline |
| Store Hours Issue | When an order is placed outside of the store hours configured on the POS. This would be a config issue or an issue where DoorDash hasn't received the latest hours update. | Store Unavailable - Hours out of Sync |
| Stale Pickup Time | Occurs when an order is canceled after the order is placed and the pickup time becomes stale. | Pickup time sent in the order is no longer available. |
| Online Ordering Disabled | When someone in the store temporarily disabled online ordering (i.e., all 3PD or just DoorDash) or when DoorDash was not activated properly on the POS during onboarding. | Store is disabled for online ordering. Store must be enabled to receive orders. |
Item out of stock Failure Reasons​
| Error bucket | Error description | Example |
|---|---|---|
| Item Unavailable | When an item is out of stock on the POS but is still in stock on the DoorDash menu. | Item Unavailable - [Item Name] - [Item ID] - Out of stock |
Menu data mismatch/out of sync Failure Reasons​
| Error bucket | Error description | Example |
|---|---|---|
| Invalid Order | This includes all misconfigurations between the DoorDash menu & POS menu, including but not limited to pricing mismatches, item configuration mismatches, and tax mismatches. | Item Missing - [Item Name] - [Item ID] - This item is no longer on the Menu |
User Flow​
- Provider sends order cancellation payload including raw failure reason.
- DoorDash receives the payload and categorizes the error.
- Based on the bucket, DoorDash’s self-healing service triggers an automated fix (e.g., refresh menu, retry order).
- Merchant and customer experience fewer failed orders and faster recovery.
FAQ​
- Which Providers are best fit?
- All integrated partners (POS, middleware, or direct-to-merchant) who process order cancellations via DoorDash. Especially relevant for providers with high item or store-level errors.
- How big of a lift is this for Providers?
- Low-to-moderate — providers already sending cancellation payloads just need to include the failure reason text consistently.
- What’s considered the “Other” bucket?
- Generic or unclear failure reasons that can’t be mapped to known categories, e.g., “Error occurred” or “Order failed - 500 error”.
- How does a Merchant access this feature?
- No action required — it runs automatically via provider integration.
- Do we need to inform Integrations Support?
- No
- What downstream impacts do we expect?
- Improved menu freshness, lower cancellations, and data standardization for HQI tracking.
Example payload​
{
"merchant_supplied_id": "DD-12345",
"order_status": "fail",
"failure_reason": "POS offline - connection timeout at store endpoint"
}