From 62e5b01b99e2172704c1363038a0ff2f1becbe5f Mon Sep 17 00:00:00 2001
From: Prasad Wangikar <prasadw@stripe.com>
Date: Fri, 17 Jul 2026 10:53:56 -0400
Subject: [PATCH 1/2] docs(specification): add error response declarations to
 Shopping service definitions

---
 source/services/shopping/mcp.openrpc.json  | 232 +++++++++----
 source/services/shopping/rest.openapi.json | 363 +++++++++++++++++++++
 2 files changed, 537 insertions(+), 58 deletions(-)

diff --git a/source/services/shopping/mcp.openrpc.json b/source/services/shopping/mcp.openrpc.json
index 2908d8d45..f57942b45 100644
--- a/source/services/shopping/mcp.openrpc.json
+++ b/source/services/shopping/mcp.openrpc.json
@@ -68,6 +68,28 @@
           }
         }
       }
+    },
+    "errors": {
+      "authentication_failed": {
+        "code": -32002,
+        "message": "Authentication failed",
+        "data": { "$ref": "../../schemas/common/types/error_response.json" }
+      },
+      "invalid_params": {
+        "code": -32602,
+        "message": "Invalid params",
+        "data": { "$ref": "../../schemas/common/types/error_response.json" }
+      },
+      "not_found": {
+        "code": -32001,
+        "message": "Resource not found",
+        "data": { "$ref": "../../schemas/common/types/error_response.json" }
+      },
+      "idempotency_conflict": {
+        "code": -32003,
+        "message": "Idempotency conflict",
+        "data": { "$ref": "../../schemas/common/types/error_response.json" }
+      }
     }
   },
   "methods": [
@@ -79,18 +101,23 @@
         {
           "name": "meta",
           "required": true,
-          "schema": {"$ref": "#/components/schemas/meta"}
+          "schema": { "$ref": "#/components/schemas/meta" }
         },
         {
           "name": "checkout",
           "required": true,
-          "schema": {"$ref": "../../schemas/shopping/checkout.json"}
+          "schema": { "$ref": "../../schemas/shopping/checkout.json" }
         }
       ],
       "result": {
         "name": "checkout",
-        "schema": {"$ref": "#/components/schemas/checkout_result"}
-      }
+        "schema": { "$ref": "#/components/schemas/checkout_result" }
+      },
+      "errors": [
+        { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/invalid_params" },
+        { "$ref": "#/components/errors/idempotency_conflict" }
+      ]
     },
     {
       "name": "get_checkout",
@@ -99,18 +126,24 @@
         {
           "name": "meta",
           "required": true,
-          "schema": {"$ref": "#/components/schemas/meta"}
+          "schema": { "$ref": "#/components/schemas/meta" }
         },
         {
           "name": "id",
           "required": true,
-          "schema": {"type": "string"}
+          "schema": {
+            "type": "string"
+          }
         }
       ],
       "result": {
         "name": "checkout",
-        "schema": {"$ref": "#/components/schemas/checkout_result"}
-      }
+        "schema": { "$ref": "#/components/schemas/checkout_result" }
+      },
+      "errors": [
+        { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/not_found" }
+      ]
     },
     {
       "name": "update_checkout",
@@ -119,23 +152,30 @@
         {
           "name": "meta",
           "required": true,
-          "schema": {"$ref": "#/components/schemas/meta"}
+          "schema": { "$ref": "#/components/schemas/meta" }
         },
         {
           "name": "id",
           "required": true,
-          "schema": {"type": "string"}
+          "schema": {
+            "type": "string"
+          }
         },
         {
           "name": "checkout",
           "required": true,
-          "schema": {"$ref": "../../schemas/shopping/checkout.json"}
+          "schema": { "$ref": "../../schemas/shopping/checkout.json" }
         }
       ],
       "result": {
         "name": "checkout",
-        "schema": {"$ref": "#/components/schemas/checkout_result"}
-      }
+        "schema": { "$ref": "#/components/schemas/checkout_result" }
+      },
+      "errors": [
+        { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/invalid_params" },
+        { "$ref": "#/components/errors/not_found" }
+      ]
     },
     {
       "name": "complete_checkout",
@@ -146,26 +186,39 @@
           "required": true,
           "schema": {
             "allOf": [
-              {"$ref": "#/components/schemas/meta"},
-              {"required": ["ucp-agent", "idempotency-key"]}
+              { "$ref": "#/components/schemas/meta" },
+              {
+                "required": [
+                  "ucp-agent",
+                  "idempotency-key"
+                ]
+              }
             ]
           }
         },
         {
           "name": "id",
           "required": true,
-          "schema": {"type": "string"}
+          "schema": {
+            "type": "string"
+          }
         },
         {
           "name": "checkout",
           "required": true,
-          "schema": {"$ref": "../../schemas/shopping/checkout.json"}
+          "schema": { "$ref": "../../schemas/shopping/checkout.json" }
         }
       ],
       "result": {
         "name": "checkout",
-        "schema": {"$ref": "#/components/schemas/checkout_result"}
-      }
+        "schema": { "$ref": "#/components/schemas/checkout_result" }
+      },
+      "errors": [
+        { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/invalid_params" },
+        { "$ref": "#/components/errors/not_found" },
+        { "$ref": "#/components/errors/idempotency_conflict" }
+      ]
     },
     {
       "name": "cancel_checkout",
@@ -176,21 +229,34 @@
           "required": true,
           "schema": {
             "allOf": [
-              {"$ref": "#/components/schemas/meta"},
-              {"required": ["ucp-agent", "idempotency-key"]}
+              { "$ref": "#/components/schemas/meta" },
+              {
+                "required": [
+                  "ucp-agent",
+                  "idempotency-key"
+                ]
+              }
             ]
           }
         },
         {
           "name": "id",
           "required": true,
-          "schema": {"type": "string"}
+          "schema": {
+            "type": "string"
+          }
         }
       ],
       "result": {
         "name": "checkout",
-        "schema": {"$ref": "#/components/schemas/checkout_result"}
-      }
+        "schema": { "$ref": "#/components/schemas/checkout_result" }
+      },
+      "errors": [
+        { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/invalid_params" },
+        { "$ref": "#/components/errors/not_found" },
+        { "$ref": "#/components/errors/idempotency_conflict" }
+      ]
     },
     {
       "name": "create_cart",
@@ -200,18 +266,23 @@
         {
           "name": "meta",
           "required": true,
-          "schema": {"$ref": "#/components/schemas/meta"}
+          "schema": { "$ref": "#/components/schemas/meta" }
         },
         {
           "name": "cart",
           "required": true,
-          "schema": {"$ref": "../../schemas/shopping/cart.json"}
+          "schema": { "$ref": "../../schemas/shopping/cart.json" }
         }
       ],
       "result": {
         "name": "cart",
-        "schema": {"$ref": "#/components/schemas/cart_result"}
-      }
+        "schema": { "$ref": "#/components/schemas/cart_result" }
+      },
+      "errors": [
+        { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/invalid_params" },
+        { "$ref": "#/components/errors/idempotency_conflict" }
+      ]
     },
     {
       "name": "get_cart",
@@ -220,18 +291,24 @@
         {
           "name": "meta",
           "required": true,
-          "schema": {"$ref": "#/components/schemas/meta"}
+          "schema": { "$ref": "#/components/schemas/meta" }
         },
         {
           "name": "id",
           "required": true,
-          "schema": {"type": "string"}
+          "schema": {
+            "type": "string"
+          }
         }
       ],
       "result": {
         "name": "cart",
-        "schema": {"$ref": "#/components/schemas/cart_result"}
-      }
+        "schema": { "$ref": "#/components/schemas/cart_result" }
+      },
+      "errors": [
+        { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/not_found" }
+      ]
     },
     {
       "name": "update_cart",
@@ -240,23 +317,30 @@
         {
           "name": "meta",
           "required": true,
-          "schema": {"$ref": "#/components/schemas/meta"}
+          "schema": { "$ref": "#/components/schemas/meta" }
         },
         {
           "name": "id",
           "required": true,
-          "schema": {"type": "string"}
+          "schema": {
+            "type": "string"
+          }
         },
         {
           "name": "cart",
           "required": true,
-          "schema": {"$ref": "../../schemas/shopping/cart.json"}
+          "schema": { "$ref": "../../schemas/shopping/cart.json" }
         }
       ],
       "result": {
         "name": "cart",
-        "schema": {"$ref": "#/components/schemas/cart_result"}
-      }
+        "schema": { "$ref": "#/components/schemas/cart_result" }
+      },
+      "errors": [
+        { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/invalid_params" },
+        { "$ref": "#/components/errors/not_found" }
+      ]
     },
     {
       "name": "cancel_cart",
@@ -267,21 +351,34 @@
           "required": true,
           "schema": {
             "allOf": [
-              {"$ref": "#/components/schemas/meta"},
-              {"required": ["ucp-agent", "idempotency-key"]}
+              { "$ref": "#/components/schemas/meta" },
+              {
+                "required": [
+                  "ucp-agent",
+                  "idempotency-key"
+                ]
+              }
             ]
           }
         },
         {
           "name": "id",
           "required": true,
-          "schema": {"type": "string"}
+          "schema": {
+            "type": "string"
+          }
         }
       ],
       "result": {
         "name": "cart",
-        "schema": {"$ref": "#/components/schemas/cart_result"}
-      }
+        "schema": { "$ref": "#/components/schemas/cart_result" }
+      },
+      "errors": [
+        { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/invalid_params" },
+        { "$ref": "#/components/errors/not_found" },
+        { "$ref": "#/components/errors/idempotency_conflict" }
+      ]
     },
     {
       "name": "search_catalog",
@@ -291,18 +388,22 @@
         {
           "name": "meta",
           "required": true,
-          "schema": {"$ref": "#/components/schemas/meta"}
+          "schema": { "$ref": "#/components/schemas/meta" }
         },
         {
           "name": "catalog",
           "required": true,
-          "schema": {"$ref": "../../schemas/shopping/catalog_search.json#/$defs/search_request"}
+          "schema": { "$ref": "../../schemas/shopping/catalog_search.json#/$defs/search_request" }
         }
       ],
       "result": {
         "name": "response",
-        "schema": {"$ref": "../../schemas/shopping/catalog_search.json#/$defs/search_response"}
-      }
+        "schema": { "$ref": "../../schemas/shopping/catalog_search.json#/$defs/search_response" }
+      },
+      "errors": [
+        { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/invalid_params" }
+      ]
     },
     {
       "name": "lookup_catalog",
@@ -312,18 +413,22 @@
         {
           "name": "meta",
           "required": true,
-          "schema": {"$ref": "#/components/schemas/meta"}
+          "schema": { "$ref": "#/components/schemas/meta" }
         },
         {
           "name": "catalog",
           "required": true,
-          "schema": {"$ref": "../../schemas/shopping/catalog_lookup.json#/$defs/lookup_request"}
+          "schema": { "$ref": "../../schemas/shopping/catalog_lookup.json#/$defs/lookup_request" }
         }
       ],
       "result": {
         "name": "response",
-        "schema": {"$ref": "../../schemas/shopping/catalog_lookup.json#/$defs/lookup_response"}
-      }
+        "schema": { "$ref": "../../schemas/shopping/catalog_lookup.json#/$defs/lookup_response" }
+      },
+      "errors": [
+        { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/invalid_params" }
+      ]
     },
     {
       "name": "get_order",
@@ -333,18 +438,25 @@
         {
           "name": "meta",
           "required": true,
-          "schema": {"$ref": "#/components/schemas/meta"}
+          "schema": { "$ref": "#/components/schemas/meta" }
         },
         {
           "name": "id",
           "required": true,
-          "schema": {"type": "string", "description": "The unique identifier of the order."}
+          "schema": {
+            "type": "string",
+            "description": "The unique identifier of the order."
+          }
         }
       ],
       "result": {
         "name": "order",
-        "schema": {"$ref": "#/components/schemas/order_result"}
-      }
+        "schema": { "$ref": "#/components/schemas/order_result" }
+      },
+      "errors": [
+        { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/not_found" }
+      ]
     },
     {
       "name": "get_product",
@@ -354,18 +466,22 @@
         {
           "name": "meta",
           "required": true,
-          "schema": {"$ref": "#/components/schemas/meta"}
+          "schema": { "$ref": "#/components/schemas/meta" }
         },
         {
           "name": "catalog",
           "required": true,
-          "schema": {"$ref": "../../schemas/shopping/catalog_lookup.json#/$defs/get_product_request"}
+          "schema": { "$ref": "../../schemas/shopping/catalog_lookup.json#/$defs/get_product_request" }
         }
       ],
       "result": {
         "name": "response",
-        "schema": {"$ref": "#/components/schemas/catalog_get_product_result"}
-      }
+        "schema": { "$ref": "#/components/schemas/catalog_get_product_result" }
+      },
+      "errors": [
+        { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/invalid_params" }
+      ]
     }
   ]
 }
diff --git a/source/services/shopping/rest.openapi.json b/source/services/shopping/rest.openapi.json
index 4ea716214..5a2219b8b 100644
--- a/source/services/shopping/rest.openapi.json
+++ b/source/services/shopping/rest.openapi.json
@@ -92,6 +92,36 @@
                 }
               }
             }
+          },
+          "400": {
+            "description": "Request body failed validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication failed or missing credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Idempotency conflict. A request with this Idempotency-Key was already processed with different parameters.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
           }
         }
       }
@@ -160,6 +190,26 @@
                 }
               }
             }
+          },
+          "401": {
+            "description": "Authentication failed or missing credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
           }
         }
       },
@@ -237,6 +287,46 @@
                 }
               }
             }
+          },
+          "400": {
+            "description": "Request body failed validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication failed or missing credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Idempotency conflict. A request with this Idempotency-Key was already processed with different parameters.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
           }
         }
       }
@@ -317,6 +407,46 @@
                 "schema": { "$ref": "#/components/schemas/checkout_response" }
               }
             }
+          },
+          "400": {
+            "description": "Request body failed validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication failed or missing credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Idempotency conflict. A request with this Idempotency-Key was already processed with different parameters.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
           }
         }
       }
@@ -391,6 +521,36 @@
                 }
               }
             }
+          },
+          "401": {
+            "description": "Authentication failed or missing credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Idempotency conflict. A request with this Idempotency-Key was already processed with different parameters.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
           }
         }
       }
@@ -436,6 +596,36 @@
                 "schema": { "$ref": "#/components/schemas/cart_response" }
               }
             }
+          },
+          "400": {
+            "description": "Request body failed validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication failed or missing credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Idempotency conflict. A request with this Idempotency-Key was already processed with different parameters.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
           }
         }
       }
@@ -474,6 +664,26 @@
                 "schema": { "$ref": "#/components/schemas/cart_response" }
               }
             }
+          },
+          "401": {
+            "description": "Authentication failed or missing credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
           }
         }
       },
@@ -517,6 +727,46 @@
                 "schema": { "$ref": "#/components/schemas/cart_response" }
               }
             }
+          },
+          "400": {
+            "description": "Request body failed validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication failed or missing credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Idempotency conflict. A request with this Idempotency-Key was already processed with different parameters.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
           }
         }
       }
@@ -557,6 +807,36 @@
                 "schema": { "$ref": "#/components/schemas/cart_response" }
               }
             }
+          },
+          "401": {
+            "description": "Authentication failed or missing credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Idempotency conflict. A request with this Idempotency-Key was already processed with different parameters.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
           }
         }
       }
@@ -601,6 +881,26 @@
                 "schema": { "$ref": "#/components/schemas/catalog_search_response" }
               }
             }
+          },
+          "400": {
+            "description": "Request body failed validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication failed or missing credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
           }
         }
       }
@@ -645,6 +945,26 @@
                 "schema": { "$ref": "#/components/schemas/catalog_lookup_response" }
               }
             }
+          },
+          "400": {
+            "description": "Request body failed validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication failed or missing credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
           }
         }
       }
@@ -683,6 +1003,26 @@
                 "schema": { "$ref": "#/components/schemas/order_response" }
               }
             }
+          },
+          "401": {
+            "description": "Authentication failed or missing credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
           }
         }
       }
@@ -727,6 +1067,26 @@
                 "schema": { "$ref": "#/components/schemas/catalog_get_product_response" }
               }
             }
+          },
+          "400": {
+            "description": "Request body failed validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication failed or missing credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/error_response"
+                }
+              }
+            }
           }
         }
       }
@@ -1021,6 +1381,9 @@
           { "$ref": "../../schemas/shopping/catalog_lookup.json#/$defs/get_product_response" },
           { "$ref": "../../schemas/common/types/error_response.json" }
         ]
+      },
+      "error_response": {
+        "$ref": "../../schemas/common/types/error_response.json"
       }
     }
   }

From 1e4b48949272d1eec21e5fcb2fd431f75821215e Mon Sep 17 00:00:00 2001
From: Prasad Wangikar <prasadw@stripe.com>
Date: Tue, 21 Jul 2026 07:19:23 -0400
Subject: [PATCH 2/2] fix(shopping): add missing error declarations to MCP
 methods for REST parity

Committed-By-Agent: claude
---
 source/services/shopping/mcp.openrpc.json | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/source/services/shopping/mcp.openrpc.json b/source/services/shopping/mcp.openrpc.json
index f57942b45..979036070 100644
--- a/source/services/shopping/mcp.openrpc.json
+++ b/source/services/shopping/mcp.openrpc.json
@@ -142,6 +142,7 @@
       },
       "errors": [
         { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/invalid_params" },
         { "$ref": "#/components/errors/not_found" }
       ]
     },
@@ -174,7 +175,8 @@
       "errors": [
         { "$ref": "#/components/errors/authentication_failed" },
         { "$ref": "#/components/errors/invalid_params" },
-        { "$ref": "#/components/errors/not_found" }
+        { "$ref": "#/components/errors/not_found" },
+        { "$ref": "#/components/errors/idempotency_conflict" }
       ]
     },
     {
@@ -307,6 +309,7 @@
       },
       "errors": [
         { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/invalid_params" },
         { "$ref": "#/components/errors/not_found" }
       ]
     },
@@ -339,7 +342,8 @@
       "errors": [
         { "$ref": "#/components/errors/authentication_failed" },
         { "$ref": "#/components/errors/invalid_params" },
-        { "$ref": "#/components/errors/not_found" }
+        { "$ref": "#/components/errors/not_found" },
+        { "$ref": "#/components/errors/idempotency_conflict" }
       ]
     },
     {
@@ -455,6 +459,7 @@
       },
       "errors": [
         { "$ref": "#/components/errors/authentication_failed" },
+        { "$ref": "#/components/errors/invalid_params" },
         { "$ref": "#/components/errors/not_found" }
       ]
     },