app/Exceptions/RagApiException.php

<?php

namespace App\Exceptions;

use Illuminate\Http\Client\Response;
use RuntimeException;
use Throwable;

class RagApiException extends RuntimeException
{
    public function __construct(
        string $message = '',
        public readonly int $statusCode = 0,
        public readonly mixed $data = null,
        ?Throwable $previous = null,
    ) {
        parent::__construct($message, $statusCode, $previous);
    }

    public static function fromResponse(Response $response): self
    {
        $data = self::parseResponseData($response);

        return new self(
            message: self::messageFromData($data),
            statusCode: $response->status(),
            data: $data,
        );
    }

    private static function parseResponseData(Response $response): mixed
    {
        $contentType = $response->header('Content-Type', '');

        if (str_contains($contentType, 'application/json')) {
            return $response->json();
        }

        $body = $response->body();

        return $body !== '' ? $body : null;
    }

    private static function messageFromData(mixed $data): string
    {
        if (is_string($data)) {
            return $data;
        }

        if (! is_array($data)) {
            return '';
        }

        foreach (['message', 'error'] as $key) {
            if (isset($data[$key]) && is_string($data[$key])) {
                return $data[$key];
            }
        }

        $detail = $data['detail'] ?? null;

        if (is_string($detail)) {
            return $detail;
        }

        if (is_array($detail)) {
            foreach ($detail as $item) {
                if (! is_array($item)) {
                    continue;
                }

                foreach (['msg', 'message'] as $key) {
                    if (isset($item[$key]) && is_string($item[$key])) {
                        return $item[$key];
                    }
                }
            }
        }

        return '';
    }
}