fix: expose fetch error in /governance/dreps/:drep_id/metadata

CHANGELOG.md

@@ -9,12 +9,26 @@ Unreleased changes are in the `master` branch.
 
 ## [Unreleased]
 
+## [0.1.84] - 2025-11-27
+
+### Added
+
+- Exposed off-chain metadata fetch errors in metadata responses in `/governance/dreps/:drep_id/metadata`
+  - Error object structure:
+    ```ts
+    {
+      "code": "HASH_MISMATCH" | "CONNECTION_ERROR" | "HTTP_RESPONSE_ERROR" | "DECODE_ERROR" | "SIZE_EXCEEDED" | "UNKNOWN_ERROR",
+      "message": "Human-readable description of the error"
+    }
+    ```
+  - If metadata are available, the `error` field is omitted
+
 ## [0.1.83] - 2025-11-25
 
 ### Fixed
 
 - `/network/eras` number format
-- added PlutusV3 to the type field of the script object, to match the actual API response types
+- Added PlutusV3 to the type field of the script object, to match the actual API response types
 
 ## [0.1.82] - 2025-10-20
 

blockfrost-openapi.yaml

@@ -1,6 +1,6 @@
 openapi: 3.0.0
 info:
-  version: 0.1.83
+  version: 0.1.84
   title: Blockfrost.io ~ API Documentation
   x-logo:
     url: https://staging.blockfrost.io/images/logo.svg
@@ -6840,6 +6840,27 @@ components:
         bytes:
           type: string
           description: Content of the metadata (raw)
+          nullable: true
+        error:
+          type: object
+          description: Present when metadata could not be fetched or validated.
+          properties:
+            code:
+              type: string
+              description: Stable machine-readable error code.
+              enum:
+                - HASH_MISMATCH
+                - CONNECTION_ERROR
+                - HTTP_RESPONSE_ERROR
+                - DECODE_ERROR
+                - SIZE_EXCEEDED
+                - UNKNOWN_ERROR
+            message:
+              type: string
+              description: Human-readable description of the error.
+          required:
+            - code
+            - message
       required:
         - drep_id
         - hex

docs/blockfrost-openapi.yaml

@@ -1,6 +1,6 @@
 openapi: 3.0.3
 info:
-  version: 0.1.83
+  version: 0.1.84
   title: Blockfrost.io ~ API Documentation
   x-logo:
     url: 'https://staging.blockfrost.io/images/logo.svg'
@@ -7174,6 +7174,27 @@ components:
         bytes:
           type: string
           description: Content of the metadata (raw)
+          nullable: true
+        error:
+          type: object
+          description: Present when metadata could not be fetched or validated.
+          properties:
+            code:
+              type: string
+              description: Stable machine-readable error code.
+              enum:
+                - HASH_MISMATCH
+                - CONNECTION_ERROR
+                - HTTP_RESPONSE_ERROR
+                - DECODE_ERROR
+                - SIZE_EXCEEDED
+                - UNKNOWN_ERROR
+            message:
+              type: string
+              description: Human-readable description of the error.
+          required:
+            - code
+            - message
       required:
         - drep_id
         - hex

openapi.json

@@ -1,7 +1,7 @@
 {
   "openapi": "3.0.3",
   "info": {
-    "version": "0.1.83",
+    "version": "0.1.84",
     "title": "Blockfrost.io ~ API Documentation",
     "x-logo": {
       "url": "https://staging.blockfrost.io/images/logo.svg",
@@ -9425,7 +9425,34 @@
           },
           "bytes": {
             "type": "string",
-            "description": "Content of the metadata (raw)"
+            "description": "Content of the metadata (raw)",
+            "nullable": true
+          },
+          "error": {
+            "type": "object",
+            "description": "Present when metadata could not be fetched or validated.",
+            "properties": {
+              "code": {
+                "type": "string",
+                "description": "Stable machine-readable error code.",
+                "enum": [
+                  "HASH_MISMATCH",
+                  "CONNECTION_ERROR",
+                  "HTTP_RESPONSE_ERROR",
+                  "DECODE_ERROR",
+                  "SIZE_EXCEEDED",
+                  "UNKNOWN_ERROR"
+                ]
+              },
+              "message": {
+                "type": "string",
+                "description": "Human-readable description of the error."
+              }
+            },
+            "required": [
+              "code",
+              "message"
+            ]
           }
         },
         "required": [

openapi.yaml

@@ -1,6 +1,6 @@
 openapi: 3.0.3
 info:
-  version: 0.1.83
+  version: 0.1.84
   title: Blockfrost.io ~ API Documentation
   x-logo:
     url: 'https://staging.blockfrost.io/images/logo.svg'
@@ -7174,6 +7174,27 @@ components:
         bytes:
           type: string
           description: Content of the metadata (raw)
+          nullable: true
+        error:
+          type: object
+          description: Present when metadata could not be fetched or validated.
+          properties:
+            code:
+              type: string
+              description: Stable machine-readable error code.
+              enum:
+                - HASH_MISMATCH
+                - CONNECTION_ERROR
+                - HTTP_RESPONSE_ERROR
+                - DECODE_ERROR
+                - SIZE_EXCEEDED
+                - UNKNOWN_ERROR
+            message:
+              type: string
+              description: Human-readable description of the error.
+          required:
+            - code
+            - message
       required:
         - drep_id
         - hex

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockfrost/openapi",
-  "version": "0.1.83",
+  "version": "0.1.84",
   "description": "OpenAPI specifications for blockfrost.io",
   "repository": "git@github.com:blockfrost/openapi.git",
   "author": "admin@blockfrost.io",

src/definitions.yaml

@@ -1,6 +1,6 @@
 openapi: 3.0.0
 info:
-  version: 0.1.83
+  version: 0.1.84
   title: Blockfrost.io ~ API Documentation
   x-logo:
     url: https://staging.blockfrost.io/images/logo.svg

src/generated-types.ts

@@ -7342,7 +7342,17 @@ export interface components {
                 [key: string]: unknown;
             } | unknown[] | number | boolean | null;
             /** @description Content of the metadata (raw) */
-            bytes: string;
+            bytes: string | null;
+            /** @description Present when metadata could not be fetched or validated. */
+            error?: {
+                /**
+                 * @description Stable machine-readable error code.
+                 * @enum {string}
+                 */
+                code: "HASH_MISMATCH" | "CONNECTION_ERROR" | "HTTP_RESPONSE_ERROR" | "DECODE_ERROR" | "SIZE_EXCEEDED" | "UNKNOWN_ERROR";
+                /** @description Human-readable description of the error. */
+                message: string;
+            };
         };
         /** @example [
          *       {

src/schemas/governance/drep_metadata.yaml

@@ -29,6 +29,27 @@ properties:
   bytes:
     type: string
     description: Content of the metadata (raw)
+    nullable: true
+  error:
+    type: object
+    description: Present when metadata could not be fetched or validated.
+    properties:
+      code:
+        type: string
+        description: Stable machine-readable error code.
+        enum:
+          - HASH_MISMATCH
+          - CONNECTION_ERROR
+          - HTTP_RESPONSE_ERROR
+          - DECODE_ERROR
+          - SIZE_EXCEEDED
+          - UNKNOWN_ERROR
+      message:
+        type: string
+        description: Human-readable description of the error.
+    required:
+      - code
+      - message
 required:
   - drep_id
   - hex

test/tests/__snapshots__/get-schema-for-endpoint.test.ts.snap

@@ -11992,12 +11992,39 @@ under which it is valid
         "properties": {
           "bytes": {
             "description": "Content of the metadata (raw)",
+            "nullable": true,
             "type": "string",
           },
           "drep_id": {
             "description": "Bech32 encoded addresses",
             "type": "string",
           },
+          "error": {
+            "description": "Present when metadata could not be fetched or validated.",
+            "properties": {
+              "code": {
+                "description": "Stable machine-readable error code.",
+                "enum": [
+                  "HASH_MISMATCH",
+                  "CONNECTION_ERROR",
+                  "HTTP_RESPONSE_ERROR",
+                  "DECODE_ERROR",
+                  "SIZE_EXCEEDED",
+                  "UNKNOWN_ERROR",
+                ],
+                "type": "string",
+              },
+              "message": {
+                "description": "Human-readable description of the error.",
+                "type": "string",
+              },
+            },
+            "required": [
+              "code",
+              "message",
+            ],
+            "type": "object",
+          },
           "hash": {
             "description": "Hash of the metadata file",
             "example": "69c0c68cb57f4a5b4a87bad896fc274678e7aea98e200fa14a1cb40c0cab1d8c"",