WinAPI error codes

This post is one of a series providing implementation examples of Windows API Functions, Types, Enums and Consts using VBA. The code in this post can be used as-is, however, if you regularly (or even just occasionally) work with Windows API declarations in VBA, you may want to see the posts Automatically add Windows API declaration(s) and Using 'F1' to view Windows API web pages which explain some of the functionality that can be added to the VBE by VBE_Extras.

When working with Windows API Functions, you will often have an error number made available to the calling code. There are, literally, thousands of error numbers, and they are listed on the Microsoft error codes page. Everything from 0 (ERROR_SUCCESS the description of which is "The operation completed successfully" ... ie no error) to 15841 (ERROR_API_UNAVAILABLE the description of which is "This API cannot be used in the context of the caller's application type").

You can get the description text associated with an error number using the FormatMessage Windows API Function, as follows ....

The description text is often more than enough, especially if you just want text that you can show to a user. However, what if you don't want the error number or the error description, rather you want the error name ... such as "ERROR_SUCCESS", "ERROR_INVALID_FUNCTION", "ERROR_ACCESS_DENIED" or "ERROR_API_UNAVAILABLE"? I find, as a developer, that there are times that the error name is much more useful than the error number (0 always means success ... but anything else is opaque to me!) and much more useful than the error description (which can sometimes be a bit vague and unclear).

So how to get the error name from the error number?

Well, the only way I know of is to manually look for the error number via the error codes page. Which is not too bad unless you need to look up different numbers again and again and again ... at which point I get very fed up.

So I decided to come up with a programmatic way of getting the error name from the error number. The attached zip file contains a standard Module (.bas file) which consists of an Enum containing members for (nearly ... see note below) every error; a public Function via which the error name can be obtained; two private Functions to support the public Function because if you combine the Functions into one then the VBE will report that the Function is too large. To use this, you simply pass the error number into the public Function and get the error name back.

To use it, download the Module and import it into your VBA project.

Using this is then quite simple ... for example ...

... or, for a specific error code ...

WinApiErrorCodes.zip

Download ZIP • 129KB

Note

Not quite every error name is included in the Enum:

• The error codes page includes a number of errors that are identified as being "obsolete" ... these are not included

• The list of error numbers on the error codes page includes 33 duplicate error numbers (ie the same number is used more than once, each time associated with a different error name ... however, the names are very closely related) ... the Enum includes only one error name for each error number

• The list of error numbers on the error codes page is "live" and I image Microsoft adds (and removes ... or marks as "obsolete") errors from time-to-time whereas the code of the Enum is static