From 1c73fbb36b8f3fcfbb803e226a9847344172e2b9 Mon Sep 17 00:00:00 2001 From: slowbackspace Date: Fri, 1 May 2026 13:41:00 +0200 Subject: [PATCH] docs: recommend gov_action_id variant for proposal metadata Co-Authored-By: Claude Opus 4.7 (1M context) --- blockfrost-openapi.yaml | 5 +- docs/blockfrost-openapi.yaml | 12 +- docs/midnight/index.html | 307 +++++++++--------- openapi.json | 2 +- openapi.yaml | 12 +- src/generated-types.ts | 3 + .../{tx_hash}/{cert_index}/metadata.yaml | 5 +- 7 files changed, 190 insertions(+), 156 deletions(-) diff --git a/blockfrost-openapi.yaml b/blockfrost-openapi.yaml index 30c1c51a..99cb1b78 100644 --- a/blockfrost-openapi.yaml +++ b/blockfrost-openapi.yaml @@ -1516,7 +1516,10 @@ paths: tags: - Cardano » Governance summary: Specific proposal metadata - description: Proposal metadata information. + description: | + Proposal metadata information. + + If this endpoint returns `404` or empty metadata for a known proposal, the off-chain metadata could not be fetched (e.g. unreachable URL or hash mismatch). Use the [`/governance/proposals/{gov_action_id}/metadata`](#tag/cardano--governance/GET/governance/proposals/{gov_action_id}/metadata) variant instead — it always returns the anchor `url` and `hash` along with an `error` object describing the fetch failure, so you can retrieve the metadata manually if needed. parameters: - in: path name: tx_hash diff --git a/docs/blockfrost-openapi.yaml b/docs/blockfrost-openapi.yaml index 89986bae..48665d59 100644 --- a/docs/blockfrost-openapi.yaml +++ b/docs/blockfrost-openapi.yaml @@ -1644,7 +1644,17 @@ paths: tags: - Cardano » Governance summary: Specific proposal metadata - description: Proposal metadata information. + description: > + Proposal metadata information. + + + If this endpoint returns `404` or empty metadata for a known proposal, + the off-chain metadata could not be fetched (e.g. unreachable URL or + hash mismatch). Use the + [`/governance/proposals/{gov_action_id}/metadata`](#tag/cardano--governance/GET/governance/proposals/{gov_action_id}/metadata) + variant instead — it always returns the anchor `url` and `hash` along + with an `error` object describing the fetch failure, so you can retrieve + the metadata manually if needed. parameters: - in: path name: tx_hash diff --git a/docs/midnight/index.html b/docs/midnight/index.html index a246162a..2bca60b8 100644 --- a/docs/midnight/index.html +++ b/docs/midnight/index.html @@ -788,9 +788,9 @@
Response
"data": { "block": { "hash": HexEncoded, - "height": 987, + "height": 123, "protocolVersion": 123, - "timestamp": 123, + "timestamp": 987, "author": HexEncoded, "ledgerParameters": HexEncoded, "parent": Block, @@ -866,7 +866,7 @@
Query
Variables
- 
{"epoch": 987}
+                  
{"epoch": 123}
@@ -875,13 +875,13 @@
Response
"data": { "committee": [ { - "epochNo": 987, + "epochNo": 123, "position": 123, "sidechainPubkeyHex": "abc123", - "expectedSlots": 123, - "auraPubkeyHex": "xyz789", - "poolIdHex": "abc123", - "spoSkHex": "abc123" + "expectedSlots": 987, + "auraPubkeyHex": "abc123", + "poolIdHex": "xyz789", + "spoSkHex": "xyz789" } ] } @@ -1110,8 +1110,8 @@
Response
"data": { "currentEpochInfo": { "epochNo": 123, - "durationSeconds": 123, - "elapsedSeconds": 123 + "durationSeconds": 987, + "elapsedSeconds": 987 } } } @@ -1164,7 +1164,7 @@
Response
"data": { "dParameterHistory": [ { - "blockHeight": 987, + "blockHeight": 123, "blockHash": HexEncoded, "timestamp": 123, "numPermissionedCandidates": 987, @@ -1254,12 +1254,12 @@
Response
"cardanoRewardAddress": CardanoRewardAddress, "dustAddress": DustAddress, "registered": true, - "nightBalance": "xyz789", + "nightBalance": "abc123", "generationRate": "abc123", "maxCapacity": "abc123", - "currentCapacity": "xyz789", + "currentCapacity": "abc123", "utxoTxHash": HexEncoded, - "utxoOutputIndex": 123 + "utxoOutputIndex": 987 } ] } @@ -1354,7 +1354,7 @@
Query
Variables
- 
{"epoch": 987, "limit": 987, "offset": 987}
+                  
{"epoch": 123, "limit": 987, "offset": 987}
@@ -1363,12 +1363,12 @@
Response
"data": { "epochPerformance": [ { - "epochNo": 123, - "spoSkHex": "xyz789", - "produced": 123, + "epochNo": 987, + "spoSkHex": "abc123", + "produced": 987, "expected": 987, - "identityLabel": "abc123", - "stakeSnapshot": "xyz789", + "identityLabel": "xyz789", + "stakeSnapshot": "abc123", "poolIdHex": "xyz789", "validatorClass": "abc123" } @@ -1514,12 +1514,12 @@
Response
{
   "data": {
     "poolMetadata": {
-      "poolIdHex": "abc123",
-      "hexId": "abc123",
-      "name": "xyz789",
+      "poolIdHex": "xyz789",
+      "hexId": "xyz789",
+      "name": "abc123",
       "ticker": "abc123",
       "homepageUrl": "abc123",
-      "logoUrl": "xyz789"
+      "logoUrl": "abc123"
     }
   }
 }
@@ -1611,7 +1611,7 @@ 
Query
Variables
- 
{"limit": 987, "offset": 123, "withNameOnly": true}
+                  
{"limit": 123, "offset": 987, "withNameOnly": false}
@@ -1620,9 +1620,9 @@
Response
"data": { "poolMetadataList": [ { - "poolIdHex": "xyz789", + "poolIdHex": "abc123", "hexId": "xyz789", - "name": "xyz789", + "name": "abc123", "ticker": "abc123", "homepageUrl": "xyz789", "logoUrl": "xyz789" @@ -1702,7 +1702,7 @@
Response
"registeredFirstValidEpochs": [ { "idKey": "abc123", - "firstValidEpoch": 987 + "firstValidEpoch": 123 } ] } @@ -1784,7 +1784,7 @@
Query
Variables
- 
{"fromEpoch": 123, "toEpoch": 123}
+                  
{"fromEpoch": 123, "toEpoch": 987}
@@ -1794,9 +1794,9 @@
Response
"registeredPresence": [ { "epochNo": 123, - "idKey": "abc123", - "source": "xyz789", - "status": "xyz789" + "idKey": "xyz789", + "source": "abc123", + "status": "abc123" } ] } @@ -1880,7 +1880,7 @@
Query
Variables
- 
{"fromEpoch": 987, "toEpoch": 123}
+                  
{"fromEpoch": 123, "toEpoch": 987}
@@ -1891,9 +1891,9 @@
Response
{ "epochNo": 987, "federatedValidCount": 123, - "federatedInvalidCount": 987, - "registeredValidCount": 123, - "registeredInvalidCount": 987, + "federatedInvalidCount": 123, + "registeredValidCount": 987, + "registeredInvalidCount": 123, "dparam": 123.45 } ] @@ -1975,7 +1975,7 @@
Query
Variables
- 
{"fromEpoch": 123, "toEpoch": 987}
+                  
{"fromEpoch": 123, "toEpoch": 123}
@@ -1983,7 +1983,7 @@
Response
{
   "data": {
     "registeredTotalsSeries": [
-      {"epochNo": 123, "totalRegistered": 987, "newlyRegistered": 987}
+      {"epochNo": 987, "totalRegistered": 123, "newlyRegistered": 987}
     ]
   }
 }
@@ -2065,12 +2065,12 @@ 
Response

     "spoByPoolId": {
       "poolIdHex": "abc123",
       "validatorClass": "xyz789",
-      "sidechainPubkeyHex": "abc123",
+      "sidechainPubkeyHex": "xyz789",
       "auraPubkeyHex": "abc123",
-      "name": "abc123",
-      "ticker": "xyz789",
-      "homepageUrl": "abc123",
-      "logoUrl": "abc123"
+      "name": "xyz789",
+      "ticker": "abc123",
+      "homepageUrl": "xyz789",
+      "logoUrl": "xyz789"
     }
   }
 }
@@ -2291,7 +2291,7 @@ 
Query
Variables
- 
{"limit": 987, "offset": 987}
+                  
{"limit": 987, "offset": 123}
@@ -2302,9 +2302,9 @@
Response
{ "poolIdHex": "abc123", "mainchainPubkeyHex": "abc123", - "sidechainPubkeyHex": "xyz789", - "auraPubkeyHex": "xyz789", - "validatorClass": "abc123" + "sidechainPubkeyHex": "abc123", + "auraPubkeyHex": "abc123", + "validatorClass": "xyz789" } ] } @@ -2384,7 +2384,7 @@
Response
"spoIdentityByPoolId": { "poolIdHex": "xyz789", "mainchainPubkeyHex": "xyz789", - "sidechainPubkeyHex": "abc123", + "sidechainPubkeyHex": "xyz789", "auraPubkeyHex": "xyz789", "validatorClass": "abc123" } @@ -2498,9 +2498,9 @@
Response
"sidechainPubkeyHex": "xyz789", "auraPubkeyHex": "abc123", "name": "abc123", - "ticker": "xyz789", + "ticker": "abc123", "homepageUrl": "xyz789", - "logoUrl": "xyz789" + "logoUrl": "abc123" } ] } @@ -2598,7 +2598,7 @@
Variables
{
   "spoSkHex": "abc123",
   "limit": 123,
-  "offset": 123
+  "offset": 987
 }
@@ -2608,14 +2608,14 @@
Response
"data": { "spoPerformanceBySpoSk": [ { - "epochNo": 123, - "spoSkHex": "xyz789", - "produced": 123, - "expected": 123, - "identityLabel": "abc123", - "stakeSnapshot": "abc123", + "epochNo": 987, + "spoSkHex": "abc123", + "produced": 987, + "expected": 987, + "identityLabel": "xyz789", + "stakeSnapshot": "xyz789", "poolIdHex": "xyz789", - "validatorClass": "xyz789" + "validatorClass": "abc123" } ] } @@ -2701,7 +2701,7 @@
Query
Variables
- 
{"limit": 123, "offset": 123}
+                  
{"limit": 987, "offset": 987}
@@ -2710,14 +2710,14 @@
Response
"data": { "spoPerformanceLatest": [ { - "epochNo": 123, - "spoSkHex": "xyz789", + "epochNo": 987, + "spoSkHex": "abc123", "produced": 123, "expected": 123, - "identityLabel": "abc123", - "stakeSnapshot": "abc123", - "poolIdHex": "abc123", - "validatorClass": "xyz789" + "identityLabel": "xyz789", + "stakeSnapshot": "xyz789", + "poolIdHex": "xyz789", + "validatorClass": "abc123" } ] } @@ -2826,10 +2826,10 @@
Query
Variables
{
-  "limit": 987,
+  "limit": 123,
   "offset": 987,
-  "search": "xyz789",
-  "orderByStakeDesc": true
+  "search": "abc123",
+  "orderByStakeDesc": false
 }
@@ -2840,17 +2840,17 @@
Response
"stakeDistribution": [ { "poolIdHex": "xyz789", - "name": "abc123", - "ticker": "xyz789", - "homepageUrl": "abc123", - "logoUrl": "abc123", + "name": "xyz789", + "ticker": "abc123", + "homepageUrl": "xyz789", + "logoUrl": "xyz789", "liveStake": "abc123", "activeStake": "xyz789", "liveDelegators": 987, - "liveSaturation": 123.45, + "liveSaturation": 987.65, "declaredPledge": "xyz789", "livePledge": "xyz789", - "stakeShare": 123.45 + "stakeShare": 987.65 } ] } @@ -2969,9 +2969,9 @@
Response
"data": { "termsAndConditionsHistory": [ { - "blockHeight": 123, + "blockHeight": 987, "blockHash": HexEncoded, - "timestamp": 123, + "timestamp": 987, "hash": HexEncoded, "url": "xyz789" } @@ -3269,9 +3269,9 @@
Response
"data": { "transactions": [ { - "id": 123, + "id": 987, "hash": HexEncoded, - "protocolVersion": 123, + "protocolVersion": 987, "raw": HexEncoded, "block": Block, "contractActions": [ContractAction], @@ -3629,9 +3629,9 @@
Response
"data": { "blocks": { "hash": HexEncoded, - "height": 987, + "height": 123, "protocolVersion": 987, - "timestamp": 123, + "timestamp": 987, "author": HexEncoded, "ledgerParameters": HexEncoded, "parent": Block, @@ -3889,10 +3889,10 @@
Response
{
   "data": {
     "dustLedgerEvents": {
-      "id": 987,
+      "id": 123,
       "raw": HexEncoded,
       "maxId": 123,
-      "protocolVersion": 123
+      "protocolVersion": 987
     }
   }
 }
@@ -4238,9 +4238,9 @@ 
Response

                   
{
   "data": {
     "zswapLedgerEvents": {
-      "id": 123,
+      "id": 987,
       "raw": HexEncoded,
-      "maxId": 987,
+      "maxId": 123,
       "protocolVersion": 123
     }
   }
@@ -4323,9 +4323,9 @@ 
Fields

                   
Example

                   
{
   "hash": HexEncoded,
-  "height": 123,
+  "height": 987,
   "protocolVersion": 987,
-  "timestamp": 123,
+  "timestamp": 987,
   "author": HexEncoded,
   "ledgerParameters": HexEncoded,
   "parent": Block,
@@ -4396,6 +4396,11 @@ 
Description
+
+
Example
+ 
true
+
+
@@ -4547,7 +4552,7 @@
Example
"sidechainPubkeyHex": "xyz789", "expectedSlots": 987, "auraPubkeyHex": "abc123", - "poolIdHex": "abc123", + "poolIdHex": "xyz789", "spoSkHex": "xyz789" } @@ -4993,7 +4998,7 @@
Fields
Example
- 
{"numPermissionedCandidates": 123, "numRegisteredCandidates": 987}
+                  
{"numPermissionedCandidates": 987, "numRegisteredCandidates": 123}
@@ -5053,7 +5058,7 @@
Fields
Example
{
-  "blockHeight": 123,
+  "blockHeight": 987,
   "blockHash": HexEncoded,
   "timestamp": 987,
   "numPermissionedCandidates": 987,
@@ -5126,10 +5131,10 @@ 
Fields

                 

                   
Example

                   
{
-  "id": 987,
+  "id": 123,
   "raw": HexEncoded,
-  "maxId": 987,
-  "protocolVersion": 123
+  "maxId": 123,
+  "protocolVersion": 987
 }
 

                 

@@ -5212,13 +5217,13 @@ 
Example

                   
{
   "cardanoRewardAddress": CardanoRewardAddress,
   "dustAddress": DustAddress,
-  "registered": false,
-  "nightBalance": "abc123",
-  "generationRate": "xyz789",
-  "maxCapacity": "abc123",
+  "registered": true,
+  "nightBalance": "xyz789",
+  "generationRate": "abc123",
+  "maxCapacity": "xyz789",
   "currentCapacity": "abc123",
   "utxoTxHash": HexEncoded,
-  "utxoOutputIndex": 123
+  "utxoOutputIndex": 987
 }
@@ -5275,9 +5280,9 @@
Fields
Example
{
-  "id": 123,
+  "id": 987,
   "raw": HexEncoded,
-  "maxId": 123,
+  "maxId": 987,
   "protocolVersion": 987,
   "output": DustOutput
 }
@@ -5371,7 +5376,7 @@ 
Possible Types

                 

                   
Example

                   
{
-  "id": 123,
+  "id": 987,
   "raw": HexEncoded,
   "maxId": 123,
   "protocolVersion": 123
@@ -5467,7 +5472,7 @@ 
Example

                   
{
   "id": 987,
   "raw": HexEncoded,
-  "maxId": 123,
+  "maxId": 987,
   "protocolVersion": 123
 }
 

@@ -5521,7 +5526,7 @@ 
Fields

               

                 

                   
Example

-                  
{"epochNo": 123, "durationSeconds": 987, "elapsedSeconds": 123}
+                  
{"epochNo": 987, "durationSeconds": 987, "elapsedSeconds": 123}
 

                 

               

@@ -5606,12 +5611,12 @@ 
Example

                   
{
   "epochNo": 987,
   "spoSkHex": "xyz789",
-  "produced": 987,
-  "expected": 123,
+  "produced": 123,
+  "expected": 987,
   "identityLabel": "abc123",
-  "stakeSnapshot": "abc123",
+  "stakeSnapshot": "xyz789",
   "poolIdHex": "xyz789",
-  "validatorClass": "xyz789"
+  "validatorClass": "abc123"
 }
 

                 

@@ -5658,7 +5663,7 @@ 
Fields

               

                 

                   
Example

-                  
{"idKey": "abc123", "firstValidEpoch": 987}
+                  
{"idKey": "abc123", "firstValidEpoch": 123}
 

                 

               

@@ -5679,7 +5684,7 @@ 
Description

               

                 

                   
Example

-                  
987.65
+                  
123.45
 

                 

               

@@ -5717,7 +5722,7 @@ 
Description

               

                 

                   
Example

-                  
123
+                  
987
 

                 

               

@@ -5770,8 +5775,8 @@ 
Example

                   
{
   "id": 123,
   "raw": HexEncoded,
-  "maxId": 123,
-  "protocolVersion": 987
+  "maxId": 987,
+  "protocolVersion": 123
 }
@@ -5843,11 +5848,11 @@
Fields
Example
{
-  "poolIdHex": "abc123",
+  "poolIdHex": "xyz789",
   "hexId": "abc123",
-  "name": "abc123",
-  "ticker": "abc123",
-  "homepageUrl": "abc123",
+  "name": "xyz789",
+  "ticker": "xyz789",
+  "homepageUrl": "xyz789",
   "logoUrl": "abc123"
 }
@@ -5908,10 +5913,10 @@
Fields
Example
{
-  "epochNo": 987,
+  "epochNo": 123,
   "idKey": "abc123",
   "source": "abc123",
-  "status": "abc123"
+  "status": "xyz789"
 }
@@ -5984,10 +5989,10 @@
Fields
Example
{
   "epochNo": 123,
-  "federatedValidCount": 123,
+  "federatedValidCount": 987,
   "federatedInvalidCount": 987,
   "registeredValidCount": 123,
-  "registeredInvalidCount": 987,
+  "registeredInvalidCount": 123,
   "dparam": 123.45
 }
@@ -6156,14 +6161,14 @@
Fields
Example
{
-  "id": 123,
+  "id": 987,
   "hash": HexEncoded,
-  "protocolVersion": 123,
+  "protocolVersion": 987,
   "raw": HexEncoded,
   "transactionResult": TransactionResult,
   "identifiers": [HexEncoded],
   "merkleTreeRoot": HexEncoded,
-  "startIndex": 123,
+  "startIndex": 987,
   "endIndex": 123,
   "fees": TransactionFees,
   "block": Block,
@@ -6263,7 +6268,7 @@ 
Fields

               

                 

                   
Example

-                  
{"id": 123, "success": false}
+                  
{"id": 987, "success": true}
 

                 

               

@@ -6442,14 +6447,14 @@ 
Fields

                 

                   
Example

                   
{
-  "poolIdHex": "abc123",
+  "poolIdHex": "xyz789",
   "validatorClass": "abc123",
-  "sidechainPubkeyHex": "xyz789",
-  "auraPubkeyHex": "xyz789",
-  "name": "abc123",
-  "ticker": "abc123",
+  "sidechainPubkeyHex": "abc123",
+  "auraPubkeyHex": "abc123",
+  "name": "xyz789",
+  "ticker": "xyz789",
   "homepageUrl": "abc123",
-  "logoUrl": "abc123"
+  "logoUrl": "xyz789"
 }
 

                 

@@ -6572,10 +6577,10 @@ 
Fields

                   
Example

                   
{
   "poolIdHex": "xyz789",
-  "mainchainPubkeyHex": "xyz789",
-  "sidechainPubkeyHex": "xyz789",
+  "mainchainPubkeyHex": "abc123",
+  "sidechainPubkeyHex": "abc123",
   "auraPubkeyHex": "xyz789",
-  "validatorClass": "abc123"
+  "validatorClass": "xyz789"
 }
@@ -6672,18 +6677,18 @@
Fields
Example
{
-  "poolIdHex": "abc123",
+  "poolIdHex": "xyz789",
   "name": "abc123",
-  "ticker": "abc123",
-  "homepageUrl": "abc123",
-  "logoUrl": "xyz789",
-  "liveStake": "abc123",
-  "activeStake": "xyz789",
-  "liveDelegators": 123,
-  "liveSaturation": 987.65,
+  "ticker": "xyz789",
+  "homepageUrl": "xyz789",
+  "logoUrl": "abc123",
+  "liveStake": "xyz789",
+  "activeStake": "abc123",
+  "liveDelegators": 987,
+  "liveSaturation": 123.45,
   "declaredPledge": "abc123",
   "livePledge": "xyz789",
-  "stakeShare": 123.45
+  "stakeShare": 987.65
 }
@@ -6837,9 +6842,9 @@
Fields
Example
{
-  "id": 123,
+  "id": 987,
   "hash": HexEncoded,
-  "protocolVersion": 123,
+  "protocolVersion": 987,
   "raw": HexEncoded,
   "block": Block,
   "contractActions": [ContractAction],
@@ -6954,11 +6959,11 @@ 
Fields

                 

                   
Example

                   
{
-  "blockHeight": 987,
+  "blockHeight": 123,
   "blockHash": HexEncoded,
   "timestamp": 987,
   "hash": HexEncoded,
-  "url": "abc123"
+  "url": "xyz789"
 }
 

                 

@@ -7132,7 +7137,7 @@ 
Fields

                   
Example

                   
{
   "paidFees": "xyz789",
-  "estimatedFees": "xyz789"
+  "estimatedFees": "abc123"
 }
@@ -7452,7 +7457,7 @@
Fields
Example
- 
{"highestTransactionId": 987}
+                  
{"highestTransactionId": 123}
@@ -7539,7 +7544,7 @@
Example
{
   "owner": UnshieldedAddress,
   "tokenType": HexEncoded,
-  "value": "xyz789",
+  "value": "abc123",
   "intentHash": HexEncoded,
   "outputIndex": 123,
   "ctime": 987,
@@ -7619,10 +7624,10 @@ 
Fields

                 

                   
Example

                   
{
-  "id": 123,
+  "id": 987,
   "raw": HexEncoded,
-  "maxId": 987,
-  "protocolVersion": 987
+  "maxId": 123,
+  "protocolVersion": 123
 }
 

                 

diff --git a/openapi.json b/openapi.json
index cbd13646..736269cb 100644
--- a/openapi.json
+++ b/openapi.json
@@ -1878,7 +1878,7 @@
           "Cardano » Governance"
         ],
         "summary": "Specific proposal metadata",
-        "description": "Proposal metadata information.",
+        "description": "Proposal metadata information.\n\nIf this endpoint returns `404` or empty metadata for a known proposal, the off-chain metadata could not be fetched (e.g. unreachable URL or hash mismatch). Use the [`/governance/proposals/{gov_action_id}/metadata`](#tag/cardano--governance/GET/governance/proposals/{gov_action_id}/metadata) variant instead — it always returns the anchor `url` and `hash` along with an `error` object describing the fetch failure, so you can retrieve the metadata manually if needed.\n",
         "parameters": [
           {
             "in": "path",
diff --git a/openapi.yaml b/openapi.yaml
index 89986bae..48665d59 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -1644,7 +1644,17 @@ paths:
       tags:
         - Cardano » Governance
       summary: Specific proposal metadata
-      description: Proposal metadata information.
+      description: >
+        Proposal metadata information.
+
+
+        If this endpoint returns `404` or empty metadata for a known proposal,
+        the off-chain metadata could not be fetched (e.g. unreachable URL or
+        hash mismatch). Use the
+        [`/governance/proposals/{gov_action_id}/metadata`](#tag/cardano--governance/GET/governance/proposals/{gov_action_id}/metadata)
+        variant instead — it always returns the anchor `url` and `hash` along
+        with an `error` object describing the fetch failure, so you can retrieve
+        the metadata manually if needed.
       parameters:
         - in: path
           name: tx_hash
diff --git a/src/generated-types.ts b/src/generated-types.ts
index f801010b..96b1dce2 100644
--- a/src/generated-types.ts
+++ b/src/generated-types.ts
@@ -1443,6 +1443,9 @@ export interface paths {
         /**
          * Specific proposal metadata
          * @description Proposal metadata information.
+         *
+         *     If this endpoint returns `404` or empty metadata for a known proposal, the off-chain metadata could not be fetched (e.g. unreachable URL or hash mismatch). Use the [`/governance/proposals/{gov_action_id}/metadata`](#tag/cardano--governance/GET/governance/proposals/{gov_action_id}/metadata) variant instead — it always returns the anchor `url` and `hash` along with an `error` object describing the fetch failure, so you can retrieve the metadata manually if needed.
+         *
          */
         get: {
             parameters: {
diff --git a/src/paths/api/governance/proposals/{tx_hash}/{cert_index}/metadata.yaml b/src/paths/api/governance/proposals/{tx_hash}/{cert_index}/metadata.yaml
index 4d4f609e..3dc2692b 100644
--- a/src/paths/api/governance/proposals/{tx_hash}/{cert_index}/metadata.yaml
+++ b/src/paths/api/governance/proposals/{tx_hash}/{cert_index}/metadata.yaml
@@ -2,7 +2,10 @@ get:
   tags:
     - Cardano » Governance
   summary: Specific proposal metadata
-  description: Proposal metadata information.
+  description: |
+    Proposal metadata information.
+
+    If this endpoint returns `404` or empty metadata for a known proposal, the off-chain metadata could not be fetched (e.g. unreachable URL or hash mismatch). Use the [`/governance/proposals/{gov_action_id}/metadata`](#tag/cardano--governance/GET/governance/proposals/{gov_action_id}/metadata) variant instead — it always returns the anchor `url` and `hash` along with an `error` object describing the fetch failure, so you can retrieve the metadata manually if needed.
   parameters:
     - in: path
       name: tx_hash