C :: API Design - Handling Platform Specific Errors

Consider the situation where you're writing a cross-platform library that has functions for creating and manipulating windows. To create a window suitable for OpenGL rendering on Windows you need to call a bunch of different functions such as GetModuleHandle, RegisterClass, CreateWindow, SetPixelFormat, GetDC, wglCreateContextGetDC and so on. All of these functions can potentially fail in one way or another and the Windows documentation doesn't even attempt to list all the different error codes that these functions return.

Let's say your function for creating a window is called create_window(). What kind of error message should you return if any of these platform specific functions fail? It could be something as simple as MultiByteToWideChar failing for some reason when you convert the UTF-8 string your API uses internally to the UTF-16 string that the Windows API expects. I've read that you're not supposed to leak implementation details from your API but what are you suppose to return when an encoding conversion fails that is supposed to be completely transparent to the user of your library?

I've decided to simply return an error code indicating a platform specific error in those cases because there's no way I can anticipate all the different errors that the Windows API might return. The problem with that is that almost all the errors end up being platform errors and without a way to actually tell what the error is then you're basically saying that some unknown error happened. That's not very useful. You could have a function called get_platform_error() that you call to obtain the exact platform error that occurred, but I'm not a fan of such a design and I've had enough trouble with GetLastError() style error handling as it is.

An alternative to that is to create a struct that represents errors and have a field in it where you can store platform specific errors. I believe this is what Apple do with their NSError error object but I'm not sure how I feel about that approach.

Assuming you implement a way to return the platform specific error code then the next part is obtaining a string that describes the error. Your library can obviously not implement error strings for every single error code that Windows might return so you're forced to use FormatMessage. The problem with that function is that you can't force it to return error messages in a specific language and it's not even guaranteed that you can get an English translation of the error string. I don't want to display error messages that mixes English with the current language the operating system uses so how do I solve this problem?

Are there any good open source libraries I could study? The ones I've looked at so far have subpar error handling at best. Many of them don't even check the return values from platform specific functions.