From 773075812fa11e9ea251ef4e539b8dc957578c83 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ianar=C3=A9=20S=C3=A9vi?= <ianare@mindee.co>
Date: Wed, 1 Jul 2026 19:01:18 +0200
Subject: [PATCH] :sparkles: add webhook error response

---
 bin/v2/parser.rb                              |  2 +-
 lib/mindee/v2/parsing.rb                      |  1 +
 .../v2/parsing/failed_inference_response.rb   | 34 +++++++++++++++++++
 .../v2/parsing/failed_inference_response.rbs  | 15 ++++++++
 spec/data                                     |  2 +-
 .../parsing/failed_inference_response_spec.rb | 17 ++++++++++
 6 files changed, 69 insertions(+), 2 deletions(-)
 create mode 100644 lib/mindee/v2/parsing/failed_inference_response.rb
 create mode 100644 sig/mindee/v2/parsing/failed_inference_response.rbs
 create mode 100644 spec/v2/parsing/failed_inference_response_spec.rb

diff --git a/bin/v2/parser.rb b/bin/v2/parser.rb
index 9c2c11ba2..3b16d3ff9 100644
--- a/bin/v2/parser.rb
+++ b/bin/v2/parser.rb
@@ -141,7 +141,7 @@ def setup_specific_options(options_parser, doc_value)
     # Initialize common options for search and product commands.
     # @param options_parser [OptionParser]
     def init_common_options(options_parser)
-      options_parser.on('-k [KEY]', '--key [KEY]', 'API key for the endpoint') { |v| @options[:api_key] = v }
+      options_parser.on('-k [KEY]', '--key [KEY]', 'Mindee V2 API key.') { |v| @options[:api_key] = v }
       options_parser.on('-o FORMAT', '--output-format FORMAT', ['raw', 'full', 'summary'],
                         'Format of the output (raw, full, summary). Default: summary') do |format|
         @options[:output_format] = format
diff --git a/lib/mindee/v2/parsing.rb b/lib/mindee/v2/parsing.rb
index 46fd19e4b..eb4770edf 100644
--- a/lib/mindee/v2/parsing.rb
+++ b/lib/mindee/v2/parsing.rb
@@ -14,3 +14,4 @@
 require_relative 'parsing/raw_text'
 require_relative 'parsing/raw_text_page'
 require_relative 'parsing/search'
+require_relative 'parsing/failed_inference_response'
diff --git a/lib/mindee/v2/parsing/failed_inference_response.rb b/lib/mindee/v2/parsing/failed_inference_response.rb
new file mode 100644
index 000000000..aad15410c
--- /dev/null
+++ b/lib/mindee/v2/parsing/failed_inference_response.rb
@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V2
+    module Parsing
+      # "Webhook payload returned when an inference fails before producing a result.
+      class FailedInferenceResponse < Mindee::V2::Parsing::CommonResponse
+        # @return [String] UUID of the failed inference.
+        attr_reader :inference_id
+        # @return [String] UUID of the model used.
+        attr_reader :model_id
+        # @return [String] Name of the input file.
+        attr_reader :file_name
+        # @return [String, Nil] Alias sent for the file, if any.
+        attr_reader :file_alias
+        # @return [Mindee::V2::Parsing::ErrorResponse] Problem details for the failure, if available.
+        attr_reader :error
+        # @return [Time] Date and time when the inference was started.
+        attr_reader :created_at
+
+        def initialize(server_response)
+          super
+
+          @inference_id = server_response['inference_id']
+          @model_id = server_response['model_id']
+          @file_name = server_response['file_name']
+          @file_alias = server_response['file_alias']
+          @error = ErrorResponse.new(server_response['error'])
+          @created_at = Time.iso8601(server_response['created_at'])
+        end
+      end
+    end
+  end
+end
diff --git a/sig/mindee/v2/parsing/failed_inference_response.rbs b/sig/mindee/v2/parsing/failed_inference_response.rbs
new file mode 100644
index 000000000..cc7f90a8a
--- /dev/null
+++ b/sig/mindee/v2/parsing/failed_inference_response.rbs
@@ -0,0 +1,15 @@
+module Mindee
+  module V2
+    module Parsing
+      class FailedInferenceResponse
+        def initialize: (Hash[String | Symbol, untyped]) -> void
+        attr_reader created_at: Time
+        attr_reader error: ::Mindee::V2::Parsing::ErrorResponse
+        attr_reader file_alias: String
+        attr_reader file_name: String
+        attr_reader inference_id: String
+        attr_reader model_id: String
+      end
+    end
+  end
+end
diff --git a/spec/data b/spec/data
index 2d7fcf8f5..e41ab97c2 160000
--- a/spec/data
+++ b/spec/data
@@ -1 +1 @@
-Subproject commit 2d7fcf8f591f6d7f40e39862965325e6a8a21874
+Subproject commit e41ab97c2833f15ea5c4edf221c2d197d212f632
diff --git a/spec/v2/parsing/failed_inference_response_spec.rb b/spec/v2/parsing/failed_inference_response_spec.rb
new file mode 100644
index 000000000..530cc6338
--- /dev/null
+++ b/spec/v2/parsing/failed_inference_response_spec.rb
@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'mindee/v2/parsing'
+
+describe Mindee::V2::Parsing::FailedInferenceResponse do
+  it 'initializes' do
+    json_file_path = File.join(V2_DATA_DIR, 'errors', 'webhook_error_500_failed.json')
+
+    response = described_class.new(JSON.parse(File.read(json_file_path)))
+    expect(response).not_to be_nil
+    expect(response.inference_id).to eq('12345678-1234-1234-1234-123456789ABC')
+    expect(response.file_name).to eq('default_sample.jpg')
+    expect(response.file_alias).to eq('dummy-alias.jpg')
+    expect(response.error.status).to eq(500)
+    expect(response.error.code).to eq('500-012')
+  end
+end