Troubleshooting Cart Errors

In calling carting-related endpoints, you may run into a 422 Validation Error HTML code. Sometimes it will be due to a malformed request, other time it will be because your user gave incomplete or incompatible information. Either way, your implementation will need an elegant way to handle these errors.

When the Grubhub API returns a 422 error, it includes an error message that details the property in the request that caused the error and a key phrase that indicates the specific problem. This article explains each of those key phrases and, when possible, covers how to handle the error.

Your particular use cases may not ever cause all of the errors below. Some features may not be available to you, like future ordering. But this list is meant to be comprehensive, so we include everything that any partner could encounter.

invalid

The property mentioned in the response was sent in the wrong format; for example, a string sent for a field that expects an integer.

Any carting endpoint can return this error.

You'll need to correct your API call or add a format on the user input that caused the error.

required

The property mentioned must be included in the request. Consult the specs for that endpoint to see how to format the required field.

Any endpoint can return this error.

invalid-cartcheckedout

You are attempting to modify a cart that has already been checked out and sent to the restaurant for fulfillment. To change or stop the order at this point, the diner will have to contact the restaurant. Whether they change or cancel the order is up to their discretion.

Any carting endpoint can return this error after the cart in question has been processed by the cart/{cart_id}/checkout endpoint.

To order additional items, create a new cart.

unprocessable

This is a generic error related to the payments that is not covered by the other payment-related errors. It usually means that the payment failed on the final check for an unknown reason.

Returned by the /carts/{cart_id}/payments and cart/{cart_id}/checkout endpoints.

We recommend that you either rebuild the cart and try again or contact your support contact at Grubhub.

invalid-notopen

The restaurant is not open and receiving orders when the item is added to the cart or at the time that the cart is sent to checkout. This can happen if a diner starts a cart while the restaurant is open but doesn't checkout until the restaurant has closed.

Returned by the POST carts/{cart_id}/lines cart/{cart_id}/checkout endpoint.

The diner will need to select items from another restaurant.

invalid-notavailablefordelivery

The selected restaurant does not deliver.

Most commonly, this will be returned by the /carts/{cart_id}/delivery_info or PUT /carts/{cart_id}/incomplete_delivery endpoints.

The diner will have to pickup their order or select items from another restaurant.

invalid-notavailablefordeliveryatdinerlocation

The restaurant does deliver, but the address given is outside of their delivery area.

This will be returned by the /carts/{cart_id}/delivery_info or PUT /carts/{cart_id}/incomplete_delivery endpoints.

The diner will have to use a different delivery address, pickup their order, or select items from another restaurant.

invalid-timecutofffordelivery

The restaurant is still open but within the window after which they stop delivering. This can happen if a diner starts a cart while the restaurant is open but doesn't checkout until later.

Returned by the POST carts/{cart_id}/lines or cart/{cart_id}/checkout endpoint.

The diner will need to change the order to pickup (if the restaurant allows it) or select items from another restaurant.

invalid-notavailableforpickup

The selected restaurant does not allow orders to be picked up.

Most commonly, this will be returned by the /carts/{cart_id}/pickup_info or PUT /carts/{cart_id}/incomplete_pickup endpoints.

The diner will have to switch to delivery or select items from another restaurant.

invalid-timecutoffforpickup

The restaurant is still open but within the window after which they stop accepting pickup orders. This can happen if a diner starts a cart while the restaurant is open but doesn't checkout until later.

Most commonly, this will be returned by the /carts/{cart_id}/pickup_info or PUT /carts/{cart_id}/incomplete_pickup endpoints.

The diner will have to switch to delivery or select items from another restaurant.

invalid-onlyonerestaurantallowed

The diner attempted to add items from multiple restaurants to a single cart. Carts can only contain items from a single restaurant.

This can be returned by the POST carts/{cart_id}/lines endpoint.

You should restrict and prevent diners from attempting to order from multiple restaurants. The diner can, instead, submit multiple orders.

invalid-fulfillmentinforequired

Neither delivery nor pickup information has been specified for the cart. In order to checkout a cart, either complete delivery or pickup information must be attached.

Can be returned by the cart/{cart_id}/checkout endpoint.

You will need to gather diner information and call either /carts/{cart_id}/delivery_info or /carts/{cart_id}/pickup_info successfully.

invalid-geocheckout

The cart does not have enough information to fulfill the order through delivery. This includes diner contact and address information. Generally, this indicates that you called PUT /carts/{cart_id}/incomplete_delivery but not /carts/{cart_id}/delivery_info.

This error can be returned from the cart/{cart_id}/checkout endpoint.

You will need to gather the data required to call /carts/{cart_id}/delivery_info successfully, then call that endpoint.

invalid-enterpickupinfo

The cart does not have enough information to fulfill the order through pickup. Pickup orders require diner contact information at a minimum to ensure that the person who picks up the food is the same one who ordered it. This usually happens because you called PUT /carts/{cart_id}/incomplete_pickup but not /carts/{cart_id}/pickup_info.

This error can be returned from the cart/{cart_id}/checkout endpoint.

You will need to pass the required data to /carts/{cart_id}/pickup_info.

invalid-orderminimumnotmet

The diner has not added enough items to their cart to meet the minimums set by the restaurant. Order minimums only apply to delivery orders.

This error can be returned from the cart/{cart_id}/checkout endpoint.

The diner will either need to add more items to their cart or cancel and try another restaurant.

invalid-cashtipnotallowed

The current restaurant does not accept tips in cash.

This error occurs with the POST /carts/{cart_id}/tip endpoint.

You'll need to apply tips to any order to this restaurant using the INCLUDE_IN_BILL type instead of CASH. We recommend that you disallow cash tips on restaurants that don't allow them by checking the restaurant field restaurant.cash_tip_allowed.

invalid-amountnotmet

The cost of the items in the cart has not been covered by the payments applied. This can happen if you allow diners to add new items to a cart after they apply payments.

This error can be returned from the cart/{cart_id}/checkout endpoint.

You'll need to request additional payment from the diner, either by amending the amount applied to an existing method or applying the remaining balance to a new method.

invalid-nonzerocashtipnotallowed

A cash tip was specified with a tip amount. When you specify the tip is in cash, you cannot also specify the amount, as there is no way to verify that amount is actually given in cash.

This error occurs with the POST /carts/{cart_id}/tip endpoint.

To avoid this error, ignore any amounts associated with cash tips.

invalid-negativetipnotallowed

Tips can only be positive numbers. This prevents diners from using the tip field to lower their bill.

This error occurs with the POST /carts/{cart_id}/tip endpoint.

To avoid this error, only allow tip amounts greater than or equal to 0.

invalid-categoryminimumnotmet

The diner has not selected enough choices to add this item to their cart. Some menu items require a specific number of choice selections in order for the item to be fulfilled.

Returned by the POST carts/{cart_id}/lines endpoint.

Make sure that when you add items to a diner's cart, they select all the required options. Consult the Adding Menu Items to Carts topic for more information.

invalid-categorymaximumexceeded

The diner has selected too many choices for the current menu item and cannot add it to the cart. While many items require a certain number of choices, some have a limit as to how many choices you can add.

Returned by the POST carts/{cart_id}/lines endpoint.

Make sure that when you add items to a diner's cart, they do not exceed the maximum number of choices. Consult the Adding Menu Items to Carts topic for more information.

invalid-maximumexceeded

The entered FreeGrub code has been used as many times as it is allowed. For most codes, the maximum number of uses is one, so you will get this response if the code has been used at all.

Returned by GET /carts/{cart_id}/bill and POST /carts/{cart_id}/payments.

The diner will not be able to use this code again, so they will need to provide payment for the cart another way.

invalid-couponnotfound

The entered FreeGrub code does not exist on our servers.

Returned by GET /carts/{cart_id}/bill and POST /carts/{cart_id}/payments.

The diner will have to double check their code or find another means of payment.

invalid-optionnotfound

The menu item option does not exist. This could happen when a diner reorders an item that has changed since their first order.

Returned by the POST carts/{cart_id}/lines endpoint.

You may need to ensure that your implementation passes choices correctly based on the current configuration of that menu item.

invalid-menuitemunavailable

The indicated menu item can no longer be ordered. The item may have become unavailable, either through menu schedules or restaurants 86-ing an item.

Returned by the POST carts/{cart_id}/lines and GET /carts/{cart_id}/bill endpoint.

The diner will need to select another menu item to continue with their order.

invalid-menuitemnotfound

The indicated menu item cannot be found. It may have been permanently removed from the restaurant menu during the time between when the diner began ordering and now.

Returned by the POST carts/{cart_id}/lines and GET /carts/{cart_id}/bill endpoint.

The diner will need to select another menu item to continue with their order.

invalid-linepricedchanged

The indicated menu item cannot be found. It may have been permanently removed from the restaurant menu during the time between when the diner began ordering and now.

Returned by the POST carts/{cart_id}/lines and GET /carts/{cart_id}/bill endpoint.

The diner will need to select another menu item to continue with their order.

invalid-notaccepted

The restaurant does not accept the specified payment method.

This error can be returned from POST /payments/partner_payment request and GET /carts/{cart_id}/bill.

The diner will have to select another payment method, and you will have to guard against incorrect and missing payment types. You can call POST /kendo/get-available-entitlement-types to see what payment types are available to your implementation.

invalid-amountexceeded

The diner has applied payments whose total amounts exceed the total on the cart. This can happen if a payment is applied to a cart, then the diner changed their cart contents.

This error can be returned from POST /payments/partner_payment request and GET /carts/{cart_id}/bill.

You will need to modify the amounts that each payment covers, either using diner input or, if they have a single payment method, changing the amount automatically.

invalid-twoindeterminatepayments

You have attempted to add a payment without an amount to a cart that already has such a payment. A payment without an amount will cover the entirety of a bill not covered by payments with fixed amounts. Two such payments wouldn't make sense, as the system would not know how to split the bill across these methods.

This error can be returned from POST /payments/partner_payment request and GET /carts/{cart_id}/bill.

The diner will need to determine how much to put on each payment method and which method will cover any remainders.

FreeGrub errors

All coupon errors will surface when attempting to apply a retrieved entitlement_id to a cart using POST /carts/{cart_id}/payments.

• CODE_NOT_FOUND - The code does not exist in our database.
• CODE_MAX_CODE_USAGE_REACHED - This code has been used as many times as allowed and can no longer be applied to carts.
• CODE_UNAVAILABLE - This code can not be used currently.
• CODE_EXPIRED - The code has expired, and can no longer be applied to carts.
• CODE_ORDER_MIN_NOT_MET - The cart has not yet reached the order minimum required by the code.
• CODE_NOT_COMBINABLE - This code cannot be combined with the codes already applied to the cart.

Future Ordering errors

Future ordering is currently in early beta. The following validation errors occur when attempting to create future orders. The only one you'll come across if you do not have future ordering enabled on your account is the last one, invalid-futureorderdisabled.

• invalid-whenforpastmaxallowedtime - Date the order is requested for is too far in the future.
• invalid-futureorder-aftercutofftime - Date the order is requested for is too close to the listed future order cutoff time for this restaurant.
• invalid-futureorder-noteditable - Cannot make an edit as the requested time is too close to the future order cutoff time for the restaurant.
• invalid-anonymousfutureordersnotallowed - A diner must be logged in to the system in order to checkout a future order.
• invalid-notavailableforfuturedelivery - The restaurant does not offer delivery at the requested time.
• invalid-notavailableforfuturepickup - The restaurant does not offer pickup at the requested time.
• invalid-futureorder-menuitemunavailable - The specified menu item is not available at the requested time.
• invalid-nolongercancellable - The diner can no longer cancel this order and must contact Grubhub care in order to do so.
• invalid-cannotcancelhold - The diner attempted to cancel this future order, but that action failed because the system could not refund the cost due to an error with the payment method.
• invalid-futureorderdisabled - The specified brand does not support future ordering.

invalid-required

You applied either your affiliate.id or affiliate.type value to a cart, but not both. If you specify one, you must specify both.

This error is returned by POST /carts.

If you want to apply your affiliate information to a cart, you need to include both the ID and type.

EXPIRED

The credit card attached as payment has expired and cannot be used.

This error is returned by POST /carts/{cart_id}/checkout.

Your diner will need to provide a new payment method.

REJECTED

The credit card attached as payment was rejected by Braintree when they tried to process it. This can be because of a typo in the information given or because the card cannot be used.

This error is returned by POST /carts/{cart_id}/checkout.

Your diner will need to enter the correct card information or provide a new payment method.

FAILED

The credit card transaction failed to complete. This could be due to server errors or other technical issues.

This error is returned by POST /carts/{cart_id}/checkout.

Attempt the transaction again or use a different payment method.

grantType

You passed an invalid grant type to the authorization endpoint.

Depending on the authorization flow you use, this could happen on several endpoints. Consult the Authentication topic.

Ensure that the value you pass as the grant_type is one of the valid ones listed in the specs.

token

You passed a null value as the token to the authorization endpoint.

Depending on the authorization flow you use, this could happen on several endpoints. Consult the Authentication topic.

Ensure that the token field is not an empty string.

code

You passed a null value as the authorization_code to the authorization endpoint.

Depending on the authorization flow you use, this could happen on several endpoints. Consult the Authentication topic.

Ensure that the code field is not an empty string.

scope

You passed an invalid scope to the authorization endpoint.

Depending on the authorization flow you use, this could happen on several endpoints. Consult the Authentication topic.

Ensure that the value you pass as the scope is one of the valid ones listed in the specs.