Build on the Partner API

Handling errors

Nobody reads documentation.

Here are the instructions for your agent. Give it this prompt: it reads the guides and the API contract, then walks you through the integration step by step, what to do, where and how.

Download agent instructions

This guide is for builders of a website or app on the Partner API.

Every endpoint answers an error in one shape. Branch on details.error; code is the general class of the error.

json

{
  "code": "aborted",
  "message": "Displayed price no longer valid",
  "details": {
    "error": "PRICE_MISMATCH",
    "errorMessage": "Displayed price no longer valid",
    "requestId": "c0ffee00-...",
    "path": "$.items[0]",
    "expectedPrice": 4500,
    "currentPrice": 4900,
    "currency": "USD",
    "currencyPrecision": 2
  }
}

Error codes

details.error	HTTP	What to do
BAD_REQUEST	400	A field is missing or invalid (`errorMessage` names it), or a cursor is bad. Fix the request, or restart the walk.
FORBIDDEN	403	Outside your inventory scope, or the storefront is closed. Do not retry.
INVALID_PRODUCT_ID	404	The product is gone: stop listing it. Or the cart has no such line: read the cart.
INVALID_CART_ID	404	Not a cart of your storefront. Create a new cart from your local copy.
INVALID_BOOKING_UUID	404	No such order placed from your carts. Show a neutral message.
PRODUCT_NOT_CARTABLE	400	The offer needs a booked time slot. Stop listing it.
CART_ITEM_LIMIT	400	More than 20 different options in a cart.
PRICE_MISMATCH	409	`expectedPrice` differs from the live price in `details.currentPrice`. Nothing was changed: update your price, ask the shopper to confirm, send it again.
RATE_LIMITED	429	More than 600 requests in a calendar minute, counted across the storefront's keys. Wait `details.retryAfterSeconds` when the answer carries it; there is no `Retry-After` header.
UPSTREAM_UNAVAILABLE	503	Groupon could not answer. Retry with backoff, except when adding cart items.
none	401	A missing, wrong, revoked or expired key; the message is the same for all four. Do not retry: alert an operator.

Retry policy

Situation	Retry?
UPSTREAM_UNAVAILABLE, a network error, a timeout, or a 5xx with no Groupon code	Yes, with exponential backoff, at most 5 tries
RATE_LIMITED	Yes, after `details.retryAfterSeconds`; without it, back off
A failure while adding items to a cart	No. Read the cart and add only what is missing
A failure while creating a cart	Yes. A retry creates a separate new cart: use the id of the call that succeeded
Reading a cart or an order	Yes. A read changes nothing
Every other code	No