diff --git a/imports-request-reply.md b/imports-request-reply.md
index 84063a7..c494380 100644
--- a/imports-request-reply.md
+++ b/imports-request-reply.md
@@ -42,6 +42,19 @@ This allows the component to perform request/reply messaging patterns.</p>
 <p>A catch all for other types of errors
 </li>
 </ul>
+<h4><a id="metadata_error"></a><code>variant metadata-error</code></h4>
+<p>Errors that can occur when adding metadata to a message</p>
+<h5>Variant Cases</h5>
+<ul>
+<li>
+<p><a id="metadata_error.not_supported"></a><code>not-supported</code></p>
+<p>Metadata is not supported by the message type
+</li>
+<li>
+<p><a id="metadata_error.invalid"></a><code>invalid</code>: option&lt;<code>string</code>&gt;</p>
+<p>Metadata is not valid for message type with optional reason
+</li>
+</ul>
 <h4><a id="message"></a><code>resource message</code></h4>
 <h2>A message with a binary payload and additional information</h2>
 <h3>Functions</h3>
@@ -95,12 +108,17 @@ sometimes described as the &quot;format&quot; type</p>
 </ul>
 <h4><a id="method_message_set_content_type"></a><code>[method]message.set-content-type: func</code></h4>
 <p>Set the content-type describing the format of the data in the message. This is
-sometimes described as the &quot;format&quot; type</p>
+sometimes described as the &quot;format&quot; type.
+Error is returned if content-type is not supported by the message type.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_set_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 <li><a id="method_message_set_content_type.content_type"></a><code>content-type</code>: <code>string</code></li>
 </ul>
+<h5>Return values</h5>
+<ul>
+<li><a id="method_message_set_content_type.0"></a> result</li>
+</ul>
 <h4><a id="method_message_data"></a><code>[method]message.data: func</code></h4>
 <p>An opaque blob of data</p>
 <h5>Params</h5>
@@ -131,20 +149,30 @@ to ensure portability across different implementors (e.g., Kafka -&gt; NATS, etc
 <li><a id="method_message_metadata.0"></a> option&lt;<a href="#metadata"><a href="#metadata"><code>metadata</code></a></a>&gt;</li>
 </ul>
 <h4><a id="method_message_add_metadata"></a><code>[method]message.add-metadata: func</code></h4>
-<p>Add a new key-value pair to the metadata, overwriting any existing value for the same key</p>
+<p>Add a new key-value pair to the metadata, overwriting any existing value for the same key.
+Error is returned if metadata is either not supported by the concrete message type or value is not valid.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_add_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 <li><a id="method_message_add_metadata.key"></a><code>key</code>: <code>string</code></li>
 <li><a id="method_message_add_metadata.value"></a><code>value</code>: <code>string</code></li>
 </ul>
+<h5>Return values</h5>
+<ul>
+<li><a id="method_message_add_metadata.0"></a> result&lt;_, <a href="#metadata_error"><a href="#metadata_error"><code>metadata-error</code></a></a>&gt;</li>
+</ul>
 <h4><a id="method_message_set_metadata"></a><code>[method]message.set-metadata: func</code></h4>
-<p>Set the metadata</p>
+<p>Set the metadata.
+Error is returned if metadata is either not supported by the concrete message type or value is not valid.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_set_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 <li><a id="method_message_set_metadata.meta"></a><code>meta</code>: <a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></li>
 </ul>
+<h5>Return values</h5>
+<ul>
+<li><a id="method_message_set_metadata.0"></a> result&lt;_, <a href="#metadata_error"><a href="#metadata_error"><code>metadata-error</code></a></a>&gt;</li>
+</ul>
 <h4><a id="method_message_remove_metadata"></a><code>[method]message.remove-metadata: func</code></h4>
 <p>Remove a key-value pair from the metadata</p>
 <h5>Params</h5>
diff --git a/imports.md b/imports.md
index 3f09021..b734d1b 100644
--- a/imports.md
+++ b/imports.md
@@ -41,6 +41,19 @@ It includes the <code>producer</code> interface for sending messages.</p>
 <p>A catch all for other types of errors
 </li>
 </ul>
+<h4><a id="metadata_error"></a><code>variant metadata-error</code></h4>
+<p>Errors that can occur when adding metadata to a message</p>
+<h5>Variant Cases</h5>
+<ul>
+<li>
+<p><a id="metadata_error.not_supported"></a><code>not-supported</code></p>
+<p>Metadata is not supported by the message type
+</li>
+<li>
+<p><a id="metadata_error.invalid"></a><code>invalid</code>: option&lt;<code>string</code>&gt;</p>
+<p>Metadata is not valid for message type with optional reason
+</li>
+</ul>
 <h4><a id="message"></a><code>resource message</code></h4>
 <h2>A message with a binary payload and additional information</h2>
 <h3>Functions</h3>
@@ -94,12 +107,17 @@ sometimes described as the &quot;format&quot; type</p>
 </ul>
 <h4><a id="method_message_set_content_type"></a><code>[method]message.set-content-type: func</code></h4>
 <p>Set the content-type describing the format of the data in the message. This is
-sometimes described as the &quot;format&quot; type</p>
+sometimes described as the &quot;format&quot; type.
+Error is returned if content-type is not supported by the message type.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_set_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 <li><a id="method_message_set_content_type.content_type"></a><code>content-type</code>: <code>string</code></li>
 </ul>
+<h5>Return values</h5>
+<ul>
+<li><a id="method_message_set_content_type.0"></a> result</li>
+</ul>
 <h4><a id="method_message_data"></a><code>[method]message.data: func</code></h4>
 <p>An opaque blob of data</p>
 <h5>Params</h5>
@@ -130,20 +148,30 @@ to ensure portability across different implementors (e.g., Kafka -&gt; NATS, etc
 <li><a id="method_message_metadata.0"></a> option&lt;<a href="#metadata"><a href="#metadata"><code>metadata</code></a></a>&gt;</li>
 </ul>
 <h4><a id="method_message_add_metadata"></a><code>[method]message.add-metadata: func</code></h4>
-<p>Add a new key-value pair to the metadata, overwriting any existing value for the same key</p>
+<p>Add a new key-value pair to the metadata, overwriting any existing value for the same key.
+Error is returned if metadata is either not supported by the concrete message type or value is not valid.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_add_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 <li><a id="method_message_add_metadata.key"></a><code>key</code>: <code>string</code></li>
 <li><a id="method_message_add_metadata.value"></a><code>value</code>: <code>string</code></li>
 </ul>
+<h5>Return values</h5>
+<ul>
+<li><a id="method_message_add_metadata.0"></a> result&lt;_, <a href="#metadata_error"><a href="#metadata_error"><code>metadata-error</code></a></a>&gt;</li>
+</ul>
 <h4><a id="method_message_set_metadata"></a><code>[method]message.set-metadata: func</code></h4>
-<p>Set the metadata</p>
+<p>Set the metadata.
+Error is returned if metadata is either not supported by the concrete message type or value is not valid.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_set_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 <li><a id="method_message_set_metadata.meta"></a><code>meta</code>: <a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></li>
 </ul>
+<h5>Return values</h5>
+<ul>
+<li><a id="method_message_set_metadata.0"></a> result&lt;_, <a href="#metadata_error"><a href="#metadata_error"><code>metadata-error</code></a></a>&gt;</li>
+</ul>
 <h4><a id="method_message_remove_metadata"></a><code>[method]message.remove-metadata: func</code></h4>
 <p>Remove a key-value pair from the metadata</p>
 <h5>Params</h5>
diff --git a/messaging-core.md b/messaging-core.md
index dd6d715..f8168cd 100644
--- a/messaging-core.md
+++ b/messaging-core.md
@@ -46,6 +46,19 @@ enabling the component to handle incoming messages without request/reply capabil
 <p>A catch all for other types of errors
 </li>
 </ul>
+<h4><a id="metadata_error"></a><code>variant metadata-error</code></h4>
+<p>Errors that can occur when adding metadata to a message</p>
+<h5>Variant Cases</h5>
+<ul>
+<li>
+<p><a id="metadata_error.not_supported"></a><code>not-supported</code></p>
+<p>Metadata is not supported by the message type
+</li>
+<li>
+<p><a id="metadata_error.invalid"></a><code>invalid</code>: option&lt;<code>string</code>&gt;</p>
+<p>Metadata is not valid for message type with optional reason
+</li>
+</ul>
 <h4><a id="message"></a><code>resource message</code></h4>
 <h2>A message with a binary payload and additional information</h2>
 <h3>Functions</h3>
@@ -99,12 +112,17 @@ sometimes described as the &quot;format&quot; type</p>
 </ul>
 <h4><a id="method_message_set_content_type"></a><code>[method]message.set-content-type: func</code></h4>
 <p>Set the content-type describing the format of the data in the message. This is
-sometimes described as the &quot;format&quot; type</p>
+sometimes described as the &quot;format&quot; type.
+Error is returned if content-type is not supported by the message type.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_set_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 <li><a id="method_message_set_content_type.content_type"></a><code>content-type</code>: <code>string</code></li>
 </ul>
+<h5>Return values</h5>
+<ul>
+<li><a id="method_message_set_content_type.0"></a> result</li>
+</ul>
 <h4><a id="method_message_data"></a><code>[method]message.data: func</code></h4>
 <p>An opaque blob of data</p>
 <h5>Params</h5>
@@ -135,20 +153,30 @@ to ensure portability across different implementors (e.g., Kafka -&gt; NATS, etc
 <li><a id="method_message_metadata.0"></a> option&lt;<a href="#metadata"><a href="#metadata"><code>metadata</code></a></a>&gt;</li>
 </ul>
 <h4><a id="method_message_add_metadata"></a><code>[method]message.add-metadata: func</code></h4>
-<p>Add a new key-value pair to the metadata, overwriting any existing value for the same key</p>
+<p>Add a new key-value pair to the metadata, overwriting any existing value for the same key.
+Error is returned if metadata is either not supported by the concrete message type or value is not valid.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_add_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 <li><a id="method_message_add_metadata.key"></a><code>key</code>: <code>string</code></li>
 <li><a id="method_message_add_metadata.value"></a><code>value</code>: <code>string</code></li>
 </ul>
+<h5>Return values</h5>
+<ul>
+<li><a id="method_message_add_metadata.0"></a> result&lt;_, <a href="#metadata_error"><a href="#metadata_error"><code>metadata-error</code></a></a>&gt;</li>
+</ul>
 <h4><a id="method_message_set_metadata"></a><code>[method]message.set-metadata: func</code></h4>
-<p>Set the metadata</p>
+<p>Set the metadata.
+Error is returned if metadata is either not supported by the concrete message type or value is not valid.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_set_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 <li><a id="method_message_set_metadata.meta"></a><code>meta</code>: <a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></li>
 </ul>
+<h5>Return values</h5>
+<ul>
+<li><a id="method_message_set_metadata.0"></a> result&lt;_, <a href="#metadata_error"><a href="#metadata_error"><code>metadata-error</code></a></a>&gt;</li>
+</ul>
 <h4><a id="method_message_remove_metadata"></a><code>[method]message.remove-metadata: func</code></h4>
 <p>Remove a key-value pair from the metadata</p>
 <h5>Params</h5>
diff --git a/messaging-request-reply.md b/messaging-request-reply.md
index e9b9abd..72bc144 100644
--- a/messaging-request-reply.md
+++ b/messaging-request-reply.md
@@ -48,6 +48,19 @@ handling incoming messages with request/reply capabilities.</p>
 <p>A catch all for other types of errors
 </li>
 </ul>
+<h4><a id="metadata_error"></a><code>variant metadata-error</code></h4>
+<p>Errors that can occur when adding metadata to a message</p>
+<h5>Variant Cases</h5>
+<ul>
+<li>
+<p><a id="metadata_error.not_supported"></a><code>not-supported</code></p>
+<p>Metadata is not supported by the message type
+</li>
+<li>
+<p><a id="metadata_error.invalid"></a><code>invalid</code>: option&lt;<code>string</code>&gt;</p>
+<p>Metadata is not valid for message type with optional reason
+</li>
+</ul>
 <h4><a id="message"></a><code>resource message</code></h4>
 <h2>A message with a binary payload and additional information</h2>
 <h3>Functions</h3>
@@ -101,12 +114,17 @@ sometimes described as the &quot;format&quot; type</p>
 </ul>
 <h4><a id="method_message_set_content_type"></a><code>[method]message.set-content-type: func</code></h4>
 <p>Set the content-type describing the format of the data in the message. This is
-sometimes described as the &quot;format&quot; type</p>
+sometimes described as the &quot;format&quot; type.
+Error is returned if content-type is not supported by the message type.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_set_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 <li><a id="method_message_set_content_type.content_type"></a><code>content-type</code>: <code>string</code></li>
 </ul>
+<h5>Return values</h5>
+<ul>
+<li><a id="method_message_set_content_type.0"></a> result</li>
+</ul>
 <h4><a id="method_message_data"></a><code>[method]message.data: func</code></h4>
 <p>An opaque blob of data</p>
 <h5>Params</h5>
@@ -137,20 +155,30 @@ to ensure portability across different implementors (e.g., Kafka -&gt; NATS, etc
 <li><a id="method_message_metadata.0"></a> option&lt;<a href="#metadata"><a href="#metadata"><code>metadata</code></a></a>&gt;</li>
 </ul>
 <h4><a id="method_message_add_metadata"></a><code>[method]message.add-metadata: func</code></h4>
-<p>Add a new key-value pair to the metadata, overwriting any existing value for the same key</p>
+<p>Add a new key-value pair to the metadata, overwriting any existing value for the same key.
+Error is returned if metadata is either not supported by the concrete message type or value is not valid.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_add_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 <li><a id="method_message_add_metadata.key"></a><code>key</code>: <code>string</code></li>
 <li><a id="method_message_add_metadata.value"></a><code>value</code>: <code>string</code></li>
 </ul>
+<h5>Return values</h5>
+<ul>
+<li><a id="method_message_add_metadata.0"></a> result&lt;_, <a href="#metadata_error"><a href="#metadata_error"><code>metadata-error</code></a></a>&gt;</li>
+</ul>
 <h4><a id="method_message_set_metadata"></a><code>[method]message.set-metadata: func</code></h4>
-<p>Set the metadata</p>
+<p>Set the metadata.
+Error is returned if metadata is either not supported by the concrete message type or value is not valid.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_set_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 <li><a id="method_message_set_metadata.meta"></a><code>meta</code>: <a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></li>
 </ul>
+<h5>Return values</h5>
+<ul>
+<li><a id="method_message_set_metadata.0"></a> result&lt;_, <a href="#metadata_error"><a href="#metadata_error"><code>metadata-error</code></a></a>&gt;</li>
+</ul>
 <h4><a id="method_message_remove_metadata"></a><code>[method]message.remove-metadata: func</code></h4>
 <p>Remove a key-value pair from the metadata</p>
 <h5>Params</h5>
diff --git a/wit/types.wit b/wit/types.wit
index 62f02f7..d3dd5c8 100644
--- a/wit/types.wit
+++ b/wit/types.wit
@@ -22,6 +22,15 @@ interface types {
         /// A catch all for other types of errors
         other(string),
     }
+
+    /// Errors that can occur when adding metadata to a message
+    variant metadata-error {
+        /// Metadata is not supported by the message type
+        not-supported,
+
+        /// Metadata is not valid for message type with optional reason
+        invalid(option<string>)
+    }
   
     /// A message with a binary payload and additional information
     resource message {
@@ -32,8 +41,9 @@ interface types {
         /// sometimes described as the "format" type
         content-type: func() -> option<string>;
         /// Set the content-type describing the format of the data in the message. This is
-        /// sometimes described as the "format" type
-        set-content-type: func(content-type: string);
+        /// sometimes described as the "format" type.
+        /// Error is returned if content-type is not supported by the message type.
+        set-content-type: func(content-type: string) -> result;
         /// An opaque blob of data
         data: func() -> list<u8>;
         /// Set the opaque blob of data for this message, discarding the old value
@@ -42,10 +52,12 @@ interface types {
         /// message. This metadata is simply decoration and should not be interpreted by a host
         /// to ensure portability across different implementors (e.g., Kafka -> NATS, etc.).
         metadata: func() -> option<metadata>;
-        /// Add a new key-value pair to the metadata, overwriting any existing value for the same key
-        add-metadata: func(key: string, value: string);
-        /// Set the metadata
-        set-metadata: func(meta: metadata);
+        /// Add a new key-value pair to the metadata, overwriting any existing value for the same key.
+        /// Error is returned if metadata is either not supported by the concrete message type or value is not valid.
+        add-metadata: func(key: string, value: string) -> result<_, metadata-error>;
+        /// Set the metadata.
+        /// Error is returned if metadata is either not supported by the concrete message type or value is not valid.
+        set-metadata: func(meta: metadata) -> result<_, metadata-error>;
         /// Remove a key-value pair from the metadata
         remove-metadata: func(key: string);
     }