Dispatch failure reasons
Last updated: September 4, 2026
Use this to understand why a quote or dispatch failed and what to do about it. Match the category or error code you're seeing to the row below.
| Category | What the message typically says | Error code / wording | Retries automatically? | What to do |
|---|---|---|---|---|
| Coverage | "Delivery address is outside the serviceable area" / "not in a supported market" / "No coverage for this region" | ineligible because of location coverage | No | Confirm the pickup and dropoff addresses. If they're correct, that location isn't served by that provider right now — try a different provider. |
| Distance | "Delivery distance exceeds maximum allowed" / "Dropoff is too far from pickup (X mi > Y mi limit)" | address_undeliverable — outside the delivery radius of the pickup location |
No | Double-check the addresses. If they're correct, the trip is too far for this provider — try another provider. |
| Hours | "Store is closed at the requested pickup time" / "outside operating hours" / "Merchant is not currently open" | none (text only) | No | Check two things, since the message won't say which: the provider's market operating hours, and your own store's set hours for that location. Fix whichever is wrong, or move the pickup time into an open window. |
| Lead time | Too soon: "Pickup time is too soon" / "before the minimum lead time." Too far out: no message appears | pickup_ready_too_early — pickup ready time cannot be in the past |
N/A | If an order looks stuck with no error, it may just be waiting for its booking window to open. If pickup is too soon, delay the requested time. |
| Capacity | "No couriers available at this time" / "No drivers available in your area" / "Service temporarily unavailable in this market" | address_undeliverable_limited_couriers — all couriers are currently busy |
Yes | Retry the quote after a short wait before treating it as a real failure. |
| Package limits | "Package exceeds maximum weight" / "Order value exceeds the allowed limit" / "Item dimensions are not supported" | invalid_params — total volume exceeds the limit |
No | Check the order's weight, dimensions, and value against the provider's limits. If it's over, split the order, choose a different provider, or arrange another way. |
| Vehicle class | "Requested vehicle type is not available" / "No couriers with the required vehicle in this area" | total volume cannot be over X; vehicle class can't be blank | No | Request a different vehicle type, or use another provider that can supply the required vehicle in that area. |
| Requirements unsupported | "Age verification is not supported" / "Signature on delivery is not available" / "Requested capability is not supported by this provider" | unsupported_package_requirements — provider does not support the following package requirements |
No | Remove the unsupported requirement from the order, or choose a provider that supports it. |
| Address quality | "Unable to geocode the provided address" / "Address could not be verified" / "Apartment or suite number is required" / "PO boxes are not supported" | unable to parse required address parts (number, street, city, zip) | No | Clean up the address — add a missing apartment or suite number, remove PO boxes, fix typos — then resubmit. |
| Contact data | "Recipient phone number is required" / "Invalid phone number format" / "This field is required." | INVALID_PHONE_NUMBER — phone number is invalid |
No | Find the named field in the error and fill in or correct it (commonly the recipient's phone number or an address field), then resubmit. |
| Provider account / config | "The provider isn't set up for this delivery" / provider-side "Store not found" / "Invalid credentials" / "Unauthorized" | none fixed | No | Check that the provider is in the selected dispatch strategy. Contact Nash support if you need more help. |
| Provider API errors | "Request timed out" / "Internal server error" / "Too many requests" / "Provider returned an unexpected response" | none specific (a generic wrapper around a 5xx, timeout, or rate-limit) | Yes | Retry the quote. If it keeps failing after a few attempts, treat it as a provider outage and contact Nash support. |
Error codes above are lightly cleaned for readability. For the full error schema and payload details, see the API reference at docs.usenash.com.