Error Codes

Below are common Return API errors. Use the code column in your integration.

Method	Endpoint	HTTP	Code	Message
POST	/v1/returns	400	40000000	original_order_id is required; duplicate item names; item not on the order; returned quantity too high; reasons count mismatch; invalid reason.
POST	/v1/returns	400	40002020	Failed to resolve origin/destination area (invalid or missing postal code / coordinate).
POST	/v1/returns	403	40300000	Unauthorized access to this order.
POST	/v1/returns	404	40400000	Order not found.
POST	/v1/returns	422	42200000	Order is not delivered; active return already exists; duplicate reference_id; origin location not found; origin name/phone/address required; origin location anchors missing.
POST	/v1/returns	422	42200000	You have reached your monthly Returns API limit.
POST	/v1/returns	422	42200002	Return tracking is not on your plan.
GET	/v1/returns, /v1/returns/:id	403	40300000	Unauthorized.
GET	/v1/returns/:id	404	40400000	Return not found.
GET	/v1/returns, /v1/returns/:id	422	42200002	Return page is not on your plan (Grow+).
POST	/v1/returns/:id/review	422	42200000	Return already has return order.
POST	/v1/returns/:id/approve	422	42200000	Return already has return order; already approved; already declined.
POST	/v1/returns/:id/decline	422	42200000	Return already has an active return order; already declined.
POST	/v1/returns/:id/confirm	422	42200000	Return is not approved; existing return order not in a finished negative status; courier insurance greater than returned items value; origin/destination incomplete.
POST	/v1/returns/:id/confirm	500	50000000	Failed to create return order.
POST	/v1/returns/:id/cancel	422	42200000	Return doesn't have return order; cannot cancel because return already {status}.
POST	/v1/returns/:id/cancel	500	50000000	Failed to cancel return order.

42200000 on create is also returned when the monthly return quota is exhausted (returns have no overage). 42200002 includes feature_key and required_tier. See Plans & limits and Errors.