Enhancing error handling

[lawinski]

Hello everyone! I would like to start a discussion and propose some changes to improve error handling 🚀

Is your feature request related to a problem? Please describe.
These enhancements aim to improve the developer experience by providing better context for handling and localizing errors. Currently, we cannot adequately identify and respond to errors using only HTTP status codes and human-readable messages.

Describe the solution you'd like

1. Support for API error codes - unify and add full support for error codes from the Auth API.
   NOTE: Currently, there are discrepancies due to two types of error responses, leading to the absence of error_code for OAuth requests (see issue #1631).
2. Custom error codes (or exceptions) for SDK errors - provide custom error codes or exceptions for internal SDK errors, allowing for more granular error handling. Many internal AuthExceptions currently provide only human-readable messages.
3. Comprehensive Documentation - provide documentation for every method with possible error codes. This will make it easier for developers to handle errors properly (see reference #485).
4. API Versioning Support - currently, there is only one API version [2024-01-01], which introduces a more unified error response structure (see reference #1377).
5. Documentation fixes - update the documentation to reflect the current state. It appears to be a copy of the JS docs and may not be accurate for Dart.

I cannot find any roadmap or information about these points, so I'll be grateful for some info/plans :)

[lawinski]

I have already started working on the error codes: PR #995

[lawinski]

Fixed by implementing error codes. The third improvement is in a separate issue, so we can close it.