Design: Unified Unsuccessful Response Support (Issue #341)

Context

REST API v3 returns error responses in a unified format distinct from v1:

v3 format:

{
  "error": {
    "code": "string",
    "message": "string",
    "validation": [
      { "message": "string", "field": "string" }
    ]
  }
}

v1 format:

{
  "error": "ERROR_CODE",
  "error_description": "Human readable message"
}

The current ApiLevelErrorHandler partially handles v3 (extracts code/message) but:

• Ignores the validation array entirely
• Detects v3 errors implicitly via "no result key" condition
• Has no DTO for the v3 error structure
• Has no ValidationException to surface field-level validation details

Approach: Full Implementation (Approach A)

Components

New files:

Modified files:

Data Flow

Detection in handle()

Incoming $responseBody
        │
        ├─ has 'error' AND 'error_description'      → v1 single error  → handleError()
        ├─ has 'error' AND is_array($error)          → v3 error         → handleError()  [NEW]
        ├─ has 'error' AND no 'result'               → v1 token error   → handleError()
        ├─ has 'result.result_error'                 → batch error      → handleError() per cmd
        └─ otherwise                                 → success, no-op

Routing in handleError()

$error = $responseBody['error']
        │
        ├─ is_array($error)  → UnsuccessfulResponseError::fromArray($error)
        │                         extracts: code, message, ValidationError[]
        │
        └─ is_string($error) → v1: errorCode = $error, errorDescription = error_description

After extraction → switch($errorCode):
        ├─ known codes         → specific exceptions (unchanged)
        └─ validation[] present → ValidationException($msg, $validationErrors)  [NEW]
           default              → BaseException

Class Contracts

ValidationError

readonly class ValidationError {
    public function __construct(
        public string $field,
        public string $message,
    ) {}
}

UnsuccessfulResponseError

readonly class UnsuccessfulResponseError {
    /** [@param](https://github.com/param) ValidationError[] $validation */
    public function __construct(
        public string $code,
        public string $message,
        public array $validation = [],
    ) {}

    public static function fromArray(array $data): self { ... }
}

ValidationException

class ValidationException extends BaseException {
    /** [@param](https://github.com/param) ValidationError[] $validationErrors */
    public function __construct(
        string $message,
        private readonly array $validationErrors = [],
        int $code = 0,
        ?\Throwable $previous = null,
    ) {}

    /** [@return](https://github.com/return) ValidationError[] */
    public function getValidationErrors(): array { ... }
}

Test Coverage

New cases in ApiLevelErrorHandlerTest data provider:

Deptrac Compliance

• ValidationError, UnsuccessfulResponseError — in Core layer, no SDK imports
• ValidationException — in Core/Exceptions, no SDK imports
• ApiLevelErrorHandler — in Core, uses only Core types
• No new layer violations introduced