Error Handling

Error Handling

How It Works

LibQurl follows libcurl's error model. Every supported function's return code is checked. When a failure is detected:

1. The error is pushed to curl.caughtErrors as a diagnostic record.
2. The method returns the error code to the caller.
3. Program execution continues. Nothing is thrown. Nothing blocks.

You decide when and how to inspect errors. A failed Sync() does not halt your script.

ret := curl.Sync(easy_handle)
if ret
    MsgBox "Transfer failed."
; script continues here regardless

The curl.caughtErrors array is capped at 1000 entries. Oldest records are discarded when the cap is exceeded. This number can be raised or lowered via curl.keepLastNumErrors := newValue, which may occasionally be useful when debugging unexpected server responses.

The caughtErrors Record

Each entry in curl.caughtErrors is an object with the following fields:

Field	Description
error code	Numeric code from the relevant libcurl enum.
error family	Which enum: CURLcode, CURLMcode, CURLSHcode, or CURLUcode.
error string1	Standard libcurl message for that code.
error string2	Detail from the handle's error buffer (CURLOPT_ERRORBUFFER).
invoked LibQurl method	The LibQurl method that triggered the check, or the full call chain for nested calls.
invoked curl function	The underlying libcurl function. e.g. curl_easy_perform.
options snapshot	An ordered array of report objects, one per relevant handle. Reads top-to-bottom as the logical call path descends.
timestamp	When the error was recorded.

Simple Error

Most raised errors produce one method and one report object:

[invoked LibQurl method] => Sync
[invoked curl function] => curl_easy_perform
[error family] => CURLcode
[error code] => 26
[error string1] => Failed to open/read local data from file/application
[error string2] => client read function EOF fail, only 0/3 of needed bytes read
[options snapshot]
    [1]
        [URL] => https://httpbin.org/put
        [UPLOAD] => 1
        [CUSTOMREQUEST] => PUT
        ...
[timestamp] => 20260914192705

This type of direct object capture is present on all supported DllCalls.

Nested Error (Call Hierarchy)

When a LibQurl method calls another LibQurl method and the inner call fails, the record captures the full call chain. The invoked LibQurl method field shows the path, and the options snapshot contains one report object per relevant handle, ordered as the call descends.

For example, AddEasyToShare → SetOpt → curl_easy_setopt produces three report objects:

[invoked LibQurl method] => AddEasyToShare\AddEasyToShare\SetOpt
[invoked curl function] => curl_easy_setopt
[error family] => CURLcode
[error code] => 3
[error string1] => ...
[options snapshot]
    [1]   ; easy_handle context
        [URL] => ...
        [UPLOAD] => ...
        ...
    [2]   ; share_handle context
        [SHARE] => ...
        ...
    [3]   ; original easy_handle state
        ...
[timestamp] => ...

The snapshot array reads top-to-bottom. Each entry is the state of one handle at the moment of failure. You do not need to reconstruct which handle was involved; it is in the record.

Finally, LibQurl comes with a basic object printer that can be used to read the captured error object:

ret := curl.Sync(easy_handle)
if ret {
    err := curl.caughtErrors[-1] ; Negative 1 = last array item = most recent capture
    MsgBox curl.PrintObj(err)
}

Where to Go Next

• Setting and Listing Options — inspect the options snapshot in context
• Easy Handle Reference — full method list with return codes