Error handling

Exception hierarchy

All SDK-specific errors extend EflLeasingException:

• EflLeasingException – base class for all SDK exceptions.
• ApiException – API-level errors (HTTP 4xx/5xx) returned by the EFL Leasing Online API.
• HttpException – transport-level errors (network failures, timeouts, invalid responses).

You should generally avoid catching \Exception and instead catch these specific classes.

ApiException and ProblemDetails

ApiException represents an error response from the EFL API. It exposes:

• HTTP status code (e.g. 400, 404, 500).
• A ProblemDetails instance with structured information.

use Imoli\EflLeasingSdk\Exception\ApiException;

try {
    $offer = $client->calculateBasicOffer($basket, $token);
} catch (ApiException $e) {
    $statusCode = $e->getStatusCode();
    $details = $e->getProblemDetails();

    // Log the error and return an appropriate response to the caller
}

ProblemDetails follows the RFC 7807 structure and typically includes fields such as:

• type
• title
• status
• detail
• instance

Use these fields for diagnostics, logging and monitoring.

HttpException

HttpException represents failures in the underlying HTTP layer, such as:

• Timeouts.
• Network connection issues.
• Invalid or malformed HTTP responses.

You should treat these as transient or infrastructure errors and decide whether to retry or fail fast.

use Imoli\EflLeasingSdk\Exception\HttpException;

try {
    $offer = $client->calculateBasicOffer($basket, $token);
} catch (HttpException $e) {
    // Log the transport error and decide whether to retry
}

Best practices

• Catch ApiException and HttpException at integration boundaries (controllers, message handlers).
• Map API errors to appropriate HTTP status codes in your own API.
• Do not expose raw ProblemDetails directly to end users; instead, log detailed information and show friendly messages.
• Monitor the frequency and content of these exceptions using your error tracking system.
• Use ProblemDetails fields (type, title, status, detail) as structured log fields rather than free-form text.
• Consider limited retries only for idempotent operations that fail with HttpException, and always log the underlying cause.