<?php
/**
 * Spacetraders API Client Library - Exception class
 *
 * This exception is thrown when API calls to the Spacetraders service
 * encounter errors such as network issues, invalid responses, authentication
 * failures, or other API-specific problems.
 *
 * @category Exception
 * @package  SpacetradersAPI
 * @author   Keith Solomon <keith@keithsolomon.net>
 * @license  MIT License
 * @version  GIT: <git_id>
 * @link     https://git.keithsolomon.net/keith/Spacetraders
 */

/**
 * Custom exception class for Spacetraders API related errors.
 *
 * @extends RuntimeException
 */
class SpacetradersApiException extends RuntimeException {
    /**
     * Error payload data from the API response.
     *
     * @var array<string,mixed>
     */
    protected array $errorPayload = array();

    /**
     * Constructor for SpacetradersApiException.
     *
     * @param string              $message      The exception message.
     * @param int                 $code         The exception code (default: 0).
     * @param array<string,mixed> $errorPayload The error payload from API response (default: empty array).
     */
    public function __construct( string $message, int $code = 0, array $errorPayload = array() ) {
        parent::__construct( $message, $code );
        $this->errorPayload = $errorPayload;
    }

    /**
     * Get the error payload from the API response.
     *
     * @return array<string,mixed>
     */
    public function getErrorPayload(): array {
        return $this->errorPayload;
    }
}