Since C is statically typed and JSON is not, and any JSON element can be a null, a number, a string, a boolean, an object, or an array, you basically have to do it as "a rip off the OOP way". Create a record type that represents a JSON value, and has a member that's a tag indicating which type of JSON value it is, and then create "subclasses" that build on this record type. To represent JSON well in C, you basically have to recreate OOP and polymorphism.
Anything that uses a JSON value will have to take a pointer to the base record type. Remember that objects are always reference types, poor C++ language design choices notwithstanding, because otherwise it screws up polymorphism, and you require polymorphism to do this right. When you find out what kind of "subclass" you're actually working with, (by checking the tag member,) you can cast your JSON Value pointer to the appropriate subclass type pointer to access the rest of the record.
I don't think this is a good idea. This introduces coupling in a very non-obvious way.
Consider a class or a service. It has clearly defined tasks, it's methods are well documented, it can be swapped out for something else that has the same interface/contract.
Suppose it encounters an exception. The service then can decide whether it is recoverable or not. That, in itself, is fine - if the service determines a failure is recoverable, it should recover. End of story.
Your version is quite different. In your question you are saying "The service decides whether the situation is recoverable by the caller". This is bad. How does your service know that? Why does it care for who calls it? Is it only callable from a very specific other class?
You mention NPEs as "general failure". It might not be. It might be a misconfiguration or bad data sent from a bad user, not programmer errors (Some may argue that it is a programmer error to not account for that possibility, but that's not the point here). Is an IO exception a "general failure"? It might mean either that you need to use a backup connection (simple recovery), or someone ripped out the network adapter from a live system (not that simple to recover from). None of your classes, save the very last thread exception handler can decide whether the app can recover from something or not.
If you change the caller code to deal with some type of exception that was previously "unrecoverable", how do you know that you need to change the part that throws this exception?
The other point I disagree with you on is:
...inheriting from RuntimeException...
...should be passed back to the users of the API since they are expecting them...
I don't think this is a good usage of unchecked exceptions.
If the users of the API are supposed to be expecting these exceptions, why not make them checked and enforce it? Then unchecked exceptions will propagate all the way up and may be logged in a specific way - that will mean exactly what you want - None of the calling code was expecting or could deal with this exception. While "expected" exceptions will have to be dealt with, even if the calling code insists that all it does is log it (or even silently swallows it).
This has the extra benefit that API changes are documented! You can add more "expected exceptions" if they are runtime - and none will notice until it's already live! Whilst with checked once you won't be able to compile if you don't deal with the situation.
Best Answer
This may be perfectly fine or perfectly sucky depending on how you handled the exception inside that class. When (when, not if) an exception arises, what happens? Perhaps there is some central error handler that you're using? How do the users of your JSONObject subclass know if something went awry?
Or do you have a guarantee that things simply can't go awry? If yes, then you should still have some sort of assertion mechanism to catch the impossible.
Exceptions and errors can be handled in myriad of ways. Most of the ways are all right as long as things crash early, with as specific error message as possible, and won't just fail silently later on.