The Kotlin SDK has started to look into mapping errors from the C-API into exceptions.

https://github.com/realm/realm-core/blob/master/src/realm.h#L175
https://github.com/realm/realm-core/blob/master/src/realm/object-store/c_api/error.cpp#L68

This poses a number of problems:

1) It isn't really documented, nor clear, where these errors are coming from.

2) By browsing the mapping code it seems like we are combining multiple different errors into a single C error number, e.g: https://github.com/realm/realm-core/blob/master/src/realm/object-store/c_api/error.cpp#L161 and https://github.com/realm/realm-core/blob/master/src/realm/object-store/c_api/error.cpp#L146

The main goal from users of the C-API is to avoid having to do manual error checks that are performed by ObjectStore anyway AND be able to report these errors back in a meaningful way.

A common example from Java is e.g. IllegalArgumentException. In many cases, errors coming from user input should map to this, which is also seen here: https://github.com/realm/realm-java/blob/master/realm/realm-library/src/main/cpp/util.cpp#L49.

At the same time, in many cases, we also want to slightly modify the exception message to be more idiomatic to the platform or context.

For that reason, we need more granular errors from Core where it is clear:

1) If the error is from user input, ideally in the error code itself, but otherwise in a description.

2) Even if an error seemingly looks the same, it is still important to capture the context because it might matter to the SDK's. E.g https://github.com/realm/realm-core/blob/master/src/realm.h#L214 should ideally be split into RLM_ERR_INTERNAL_INDEX_OUT_OF_BOUNDS, RLM_ERR_LIST_INDEX_OUT_OF_BOUNDS, RLM_ERR_RESULT_INDEX_OUT_OF_BOUNDS.

I do realize this is probably quite a significant refactor of how ObjectStore/Core current work, but the alternative right now is that SDK's have to implement their own checks which is a lot of duplicated work.

Other issues that touch upon the same issue:
https://github.com/realm/realm-core/issues/3817
https://github.com/realm/realm-core/issues/4191
https://github.com/realm/realm-core/issues/4835

This might also be relevant for the scope for the public API definition of Core:
https://docs.google.com/document/d/1CREV9wDp5aLxUbXjfk14uIi2A-W6K5ySHGnRtxS8IIA/edit#heading=h.uqpta4k6ounk