From 1772627b10c0fdd89fbd72905ba19f7833961b74 Mon Sep 17 00:00:00 2001
From: yoeriwalstra <yoeri@myparcel.com>
Date: Fri, 22 May 2026 12:54:44 +0200
Subject: [PATCH 1/3] fix ExceptionInterface error code order

---
 src/Exceptions/Interfaces/ExceptionInterface.php | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/Exceptions/Interfaces/ExceptionInterface.php b/src/Exceptions/Interfaces/ExceptionInterface.php
index 2c3e394..dd55d59 100644
--- a/src/Exceptions/Interfaces/ExceptionInterface.php
+++ b/src/Exceptions/Interfaces/ExceptionInterface.php
@@ -22,11 +22,6 @@ interface ExceptionInterface extends JsonSchemaErrorInterface
         'title' => 'Resource Not Found',
     ];
 
-    const RESOURCE_HANDLED_BY_3RD_PARTY = [
-        'code'  => '10014',
-        'title' => 'Resource Handled By 3rd Party',
-    ];
-
     const INVALID_JSON_SCHEMA = [
         'code'  => '10003',
         'title' => 'Invalid JSON Schema',
@@ -82,6 +77,11 @@ interface ExceptionInterface extends JsonSchemaErrorInterface
         'title' => 'Action not allowed.',
     ];
 
+    const RESOURCE_HANDLED_BY_3RD_PARTY = [
+        'code'  => '10014',
+        'title' => 'Resource Handled By 3rd Party',
+    ];
+
     // External API related errors 13000 - 13999
     const EXTERNAL_REQUEST_ERROR = [
         'code'  => '13001',

From bb56292b4a2e24bdbcac46cbb4239ea1b08dd62d Mon Sep 17 00:00:00 2001
From: yoeriwalstra <yoeri@myparcel.com>
Date: Fri, 22 May 2026 12:55:06 +0200
Subject: [PATCH 2/3] update ExceptionInterface AUTH_MISSING_SCOPE title

---
 src/Exceptions/Interfaces/ExceptionInterface.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Exceptions/Interfaces/ExceptionInterface.php b/src/Exceptions/Interfaces/ExceptionInterface.php
index dd55d59..924869b 100644
--- a/src/Exceptions/Interfaces/ExceptionInterface.php
+++ b/src/Exceptions/Interfaces/ExceptionInterface.php
@@ -121,7 +121,7 @@ interface ExceptionInterface extends JsonSchemaErrorInterface
 
     const AUTH_MISSING_SCOPE = [
         'code'  => '14004',
-        'title' => 'Access Token Is Invalid',
+        'title' => 'Missing scope in access token',
     ];
 
     const AUTH_SERVER_EXCEPTION = [

From 5953963bfc8f8ca1049e516fb6b685038fe87e5d Mon Sep 17 00:00:00 2001
From: yoeriwalstra <yoeri@myparcel.com>
Date: Fri, 22 May 2026 12:55:20 +0200
Subject: [PATCH 3/3] add doc blocks to a few exceptions

---
 src/Exceptions/ForbiddenException.php        | 4 ++--
 src/Exceptions/MissingScopeException.php     | 8 ++++++--
 src/Exceptions/ResourceNotFoundException.php | 4 ++++
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/src/Exceptions/ForbiddenException.php b/src/Exceptions/ForbiddenException.php
index 8dd800b..2088866 100644
--- a/src/Exceptions/ForbiddenException.php
+++ b/src/Exceptions/ForbiddenException.php
@@ -8,8 +8,8 @@
 use Throwable;
 
 /**
- * This exception should be thrown when the requesting user does not have rights to perform a specific action on a
- * requested resource.
+ * This exception should be thrown when the requesting user doesn't have
+ * the permission to perform a specific action on a requested resource.
  */
 class ForbiddenException extends AbstractException
 {
diff --git a/src/Exceptions/MissingScopeException.php b/src/Exceptions/MissingScopeException.php
index bc6a4ac..39853e4 100644
--- a/src/Exceptions/MissingScopeException.php
+++ b/src/Exceptions/MissingScopeException.php
@@ -8,6 +8,10 @@
 use Symfony\Component\HttpFoundation\Response;
 use Throwable;
 
+/**
+ * This exception should be thrown when the requesting user
+ * doesn't have the required scopes in his (client) access token
+ */
 class MissingScopeException extends AbstractException
 {
     use EnumTrait;
@@ -16,10 +20,10 @@ public function __construct(array $scopeSlugs, Throwable $previous = null)
     {
         $scopeStrings = collect($scopeSlugs)
             ->map(fn (mixed $scopeSlug) => $this->getEnumValue($scopeSlug))
-            ->toArray();
+            ->join(', ');
 
         parent::__construct(
-            'The used access token does not contain the required scope(s): ' . implode(', ', $scopeStrings) . '.',
+            'The used access token does not contain the required scope(s): ' . $scopeStrings . '.',
             self::AUTH_MISSING_SCOPE,
             Response::HTTP_FORBIDDEN,
             $previous,
diff --git a/src/Exceptions/ResourceNotFoundException.php b/src/Exceptions/ResourceNotFoundException.php
index 3f983d3..61d02bb 100644
--- a/src/Exceptions/ResourceNotFoundException.php
+++ b/src/Exceptions/ResourceNotFoundException.php
@@ -9,6 +9,10 @@
 use Throwable;
 use UnitEnum;
 
+/**
+ * This exception should be thrown when a user attempts to fetch a resource
+ * which he doesn't have access to based on his permissions
+ */
 class ResourceNotFoundException extends AbstractException
 {
     use EnumTrait;