docs: Document ConnectionException for API library transport errors#561
Conversation
Add a subsection to the REST API 'Error handling' guide describing the new Mautic\Exception\ConnectionException thrown by the API library when a request can't reach Mautic (DNS, timeout, TLS). Covers the message format, the AbstractApiException/\Exception hierarchy (backward compatibility), and retrieving the underlying transport exception via getPrevious(). Refs mautic/api-library#349
| Handling connection errors with the API library | ||
| ------------------------------------------------ | ||
|
|
||
| The preceding JSON error responses only apply when Mautic receives your request and returns a response. If you're using the Mautic API library and the request can't reach Mautic at all - for example, the host doesn't resolve, the connection times out, or the secure handshake fails - the library throws a ``Mautic\Exception\ConnectionException`` instead. Its message names the target URL and the underlying transport error, so you can tell a connectivity problem apart from an error Mautic returns. For cURL-based clients, the message includes the original cURL error text. |
There was a problem hiding this comment.
Documents the new Mautic\Exception\ConnectionException and its message format. In lib/Auth/AbstractAuth.php, makeRequest() catches Psr\Http\Client\ClientExceptionInterface from sendRequest() and rethrows ConnectionException with sprintf('Could not connect to the Mautic API at %s: %s', $url, $exception->getMessage()), so the message names the target URL and the underlying transport error (the cURL error text for cURL-based clients).
Source: https://github.com/mautic/api-library/pull/349/files
|
|
||
| The preceding JSON error responses only apply when Mautic receives your request and returns a response. If you're using the Mautic API library and the request can't reach Mautic at all - for example, the host doesn't resolve, the connection times out, or the secure handshake fails - the library throws a ``Mautic\Exception\ConnectionException`` instead. Its message names the target URL and the underlying transport error, so you can tell a connectivity problem apart from an error Mautic returns. For cURL-based clients, the message includes the original cURL error text. | ||
|
|
||
| ``ConnectionException`` extends the library's ``AbstractApiException``, which in turn extends PHP's ``\Exception``. Existing code that catches ``\Exception`` keeps working and simply receives a clearer message. To inspect the underlying transport failure, call ``getPrevious()`` on the caught exception to get the original client exception. |
There was a problem hiding this comment.
Backs the hierarchy and backward-compatibility statement: ConnectionException extends AbstractApiException (which extends \Exception), so existing catch (\Exception) callers keep working. The getPrevious() guidance reflects the throw passing the original client exception as $previous (throw new ConnectionException($message, (int) $exception->getCode(), $exception)); AbstractApiException::__construct was widened from ?\Exception to ?\Throwable to allow it.
Source: https://github.com/mautic/api-library/pull/349/files
2 participants
Open this suggestion in Promptless to view citations and reasoning process
Adds a "Handling connection errors with the API library" subsection to the REST API getting-started guide's Error handling section. It documents the new Mautic\Exception\ConnectionException (api-library PR #349) thrown when a request can't reach Mautic (host unresolved, connection timeout, TLS handshake failure), its message format, the AbstractApiException/\Exception hierarchy and backward compatibility, and retrieving the underlying transport exception via getPrevious(), with a PHP catch example.
Trigger Events
Tip: Tell your friends working on non-commercial open-source projects to apply for free Promptless access at promptless.ai/oss ❤️