Errors

Error format and every error code the API can return.

Errors use RFC 9457 problem details with Content-Type: application/problem+json.

{
  "title": "Wishlist name taken",
  "status": 409,
  "code": "WISHLIST_NAME_TAKEN",
  "message": "A wishlist with this name already exists",
  "messageKey": "error_wishlist_name_already_exists"
}

code · string · required

Stable, machine-readable code. Switch on this field.

status · number · required

HTTP status.

title · string · required

The code in sentence case.

message · string

English description.

messageKey · string | null

Key of the merchant’s own text in widgetSettings from GET /settings. See Showing messages to shoppers.

messageParams · object

Values for placeholders in the message, such as { "remaining": "2" }.

errors · array

Field errors on 422 VALIDATION_FAILED: [{ "field": "name", "message": "name is required." }].

wishlistId · number

Only on SHARED_LIST_ALREADY_SAVED: the shopper’s existing copy.

​

Error codes

HTTP	Code	When
400	MALFORMED_REQUEST	Body is not a JSON object, or a numeric path ID contains non-digits
401	UNAUTHENTICATED	API key or shop missing or wrong, app not installed
401	CUSTOMER_REQUIRED	No shopper identity, unknown customer, guest without session ID
401	SHARE_LOGIN_REQUIRED	An emailed share was opened by a shopper who is not logged in
403	API_ACCESS_NOT_IN_PLAN	Plan lacks API Access
403	GUEST_DISABLED	Guest wishlists are off for this store
403	FEATURE_NOT_IN_PLAN	Sharing or email sharing not in the plan, or turned off by the merchant
403	PAGE_DISABLED	The merchant turned off the wishlist page or the shared wishlist page
403	PLAN_LIMIT_REACHED	The store or shopper reached a wishlist limit. messageParams.remaining may be set.
403	WISHLIST_PRIVATE	The list belongs to someone else, or a private list was shared
403	NOT_OWNER	Only the owner can do this
403	SHARE_LINK_TAKEN	The share link was already opened by another shopper. Each link opens for one person.
403	SHARE_EMAIL_MISMATCH	The logged-in email is not the one the list was shared with
404	ROUTE_NOT_FOUND	Unknown path
404	WISHLIST_NOT_FOUND	List does not exist or is not the shopper’s
404	ITEM_NOT_FOUND	Item does not exist or is not in that list
404	SHARE_NOT_FOUND	Share or link does not exist or was stopped
405	METHOD_NOT_ALLOWED	Path exists but not with this method. See the Allow header.
409	WISHLIST_NAME_TAKEN	The shopper already has a list with this name
409	ITEM_ALREADY_IN_WISHLIST	The variant is already in the target list
409	SINGLE_LIST_MODE	Create (after the first list), delete or move while the store is in single-list mode
409	SHARED_LIST_ALREADY_SAVED	Already saved, nothing new to copy
410	SHARE_REVOKED	The owner removed this shopper’s access
410	VERSION_RETIRED	This API version is switched off. Update your app.
422	VALIDATION_FAILED	A field is missing or invalid (e.g. a name longer than 75 characters)
422	CANNOT_SAVE_OWN_WISHLIST	A shopper tried to save their own list
429	RATE_LIMITED	Too many requests. See Rate limits.
500	INTERNAL_ERROR	Unexpected error. Safe to retry.
503	SHARE_VERIFY_FAILED	Could not verify the shopper’s email right now. Retry shortly.