From 37717b3548933ebc80e31c10aa4c8a6d30aff259 Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Thu, 29 Jan 2026 21:18:56 +0000
Subject: [PATCH] feat(api): add invalidStatus and providerError response
 helpers

Add two new response methods to HasApiResponses trait:
- invalidStatusResponse(): for operations blocked by resource status
- providerErrorResponse(): for external provider failures

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/Api/Concerns/HasApiResponses.php | 32 ++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/src/Api/Concerns/HasApiResponses.php b/src/Api/Concerns/HasApiResponses.php
index b86125d..3ab973b 100644
--- a/src/Api/Concerns/HasApiResponses.php
+++ b/src/Api/Concerns/HasApiResponses.php
@@ -89,4 +89,36 @@ trait HasApiResponses
             'errors' => $errors,
         ], 422);
     }
+
+    /**
+     * Return an invalid status error response.
+     *
+     * Used when an operation cannot be performed due to the resource's current status.
+     */
+    protected function invalidStatusResponse(string $message): JsonResponse
+    {
+        return response()->json([
+            'error' => 'invalid_status',
+            'message' => $message,
+        ], 422);
+    }
+
+    /**
+     * Return a provider error response.
+     *
+     * Used when an external provider operation fails.
+     */
+    protected function providerErrorResponse(string $message, ?string $provider = null): JsonResponse
+    {
+        $response = [
+            'error' => 'provider_error',
+            'message' => $message,
+        ];
+
+        if ($provider !== null) {
+            $response['provider'] = $provider;
+        }
+
+        return response()->json($response, 400);
+    }
 }