The Engine reports failures through exceptions, listener notifications, and asynchronous operation results. Handle each channel used by your application; a try/catch around an API call does not replace a listener or observing the result of an asynchronous operation.
Engine exceptions derive from std::exception. Catch specific types such as OnixS::FIX::LinkErrorException and OnixS::FIX::TimeoutException, declared in <OnixS/FIXEngine/FIX/Exception.h>, before a general catch (const std::exception &) handler.
| Channel | Where the application receives it | What it means and how to respond |
|---|---|---|
| Immediate exception | The API call throws to its caller. An asynchronous method can also throw before returning a future. | The call did not return normally. Catch the exception and follow that operation's recovery rules; do not assume that it had no side effects or is safe to retry. |
| Engine notification | OnixS::FIX::IEngineListener::onError or OnixS::FIX::IEngineListener::onWarning. | An Engine condition was detected; it need not correspond to a particular application call or session. Record the reason and description and follow the guidance for that reason. |
| Session notification | OnixS::FIX::ISessionListener::onError or OnixS::FIX::ISessionListener::onWarning. | A condition was detected for the supplied session. Record the reason and description. Interpret it together with the operation result and session state; a notification alone does not tell you whether the operation completed. |
| Asynchronous result | OnixS::Threading::SharedFuture::get() on the future returned by asynchronous logon or logout. | Returning a future does not guarantee success. get() waits if necessary, then returns on success or throws on failure. Observe the result outside callbacks and threads needed for the operation to progress. |
These channels can overlap. For example, an exception thrown from an outbound message callback is reported through onError with OnixS::FIX::ErrorReason::ExceptionInEventHandler and propagated by the application sending call that triggered the callback. For Engine-originated messages, there is no application sending call to receive that exception, so it is reported through onError only. See Sending Messages from Outbound Callbacks for the affected calls and sequence-number recovery requirements.
An exception or notification does not universally mean that the session disconnected, that state changes were rolled back, or that retrying is safe. A warning is not necessarily harmless: for example, OnixS::FIX::WarningReason::LinkError reports a communication link error. Use the operation's API contract and the reported reason to decide whether to correct input, allow configured recovery to proceed, or stop processing and investigate. Avoid unconditional retries or sequence-number resets.
OnixS::FIX::Session::state() gives a snapshot of the current state; OnixS::FIX::ISessionListener::onStateChange reports a state transition. Neither guarantees that the session will remain in that state or that a subsequent operation will succeed. See Understanding Session States and the relevant operation's API reference.
Keep listeners short and avoid recursive error handling. Copy reason and description values into application-owned storage before retaining them for later processing. Do not wait for an asynchronous logon or logout result from a callback needed to complete it. See Callback Safety, Callback Data Lifetime, and Deferred Processing and Shutdown for threading and cleanup rules.
The combined example in Asynchronous Logon/Logout shows session listeners, exception handling, and future completion on an application thread.
