Add additional SyncError types, explain what they are, when then can happen, and how to handle them

[drmarkpowell]

Is there something wrong with existing docs content, or is something missing from the docs?

Missing

If this is related to existing docs content, what page or pages are affected?

https://www.mongodb.com/docs/realm/sdk/swift/sync/handle-sync-errors/

Which SDK does this issue affect?

Swift and maybe others

What would you like to see in the docs that isn't already there?

There is a detailed explanation here of Client Reset errors and how they may be dealt with, and that is very helpful, please maintain that.

Also though, there are other error types in this category:

• clientSessionError
• clientUserError
• clientInternalError
• underlyingAuthError
• permissionDeniedError

These types of Sync Error have no documented details on the page I linked above, and it would be very helpful to add them.
For our products that use Realm, the expectations of the organization I work for are that any type of errors like these that can happen are fully understood and that any and all precautions taken to handle them gracefully (or at least reasonably) to get users back to a working app state as soon as possible and in as automated a way as possible.

If the content is technical, can you link to an example implementation?

Realm SDK docs for RLMSyncError

Where do you feel this content belongs?

Handling Realm Sync Errors

Perhaps add sub-pages under this heading to better organize the larger amount of content. Client reset for example is right now the bulk of the page and maybe needs its own page.

Other Comments

[dacharyc]

Thank you for the feedback, @drmarkpowell ! You're right, we should do a better job of exposing errors and their resolutions in the SDK documentation. I'll talk with the team about scoping a bigger-picture error handling project during our upcoming planning process. In the short term, I'll add a link from this page to the Sync Error documentation page in the App Services documentation where we have historically maintained information about error messages.

[drmarkpowell]

Dachary, Thanks for the quick reply and the app services info link…that’s a lot of detail! Perhaps the last table of “Session level errors” is most relevant to the Realm “Handling sync errors” topic? I’ll leave that for the experts to say. Still, there are 25 error codes there and only ~6 enumerated codes in the Swift API for RLMSyncError…so maybe there is some summarization or consolidation going on? Adding additional docs will help a lot to answer all these questions, no? ;)

…

-Mark

On Jan 11, 2023, at 11:22 AM, Dachary ***@***.***> wrote: Thank you for the feedback, @drmarkpowell <https://github.com/drmarkpowell> ! You're right, we should do a better job of exposing errors and their resolutions in the SDK documentation. I'll talk with the team about scoping a bigger-picture error handling project during our upcoming planning process. In the short term, I'll add a link from this page to the Sync Error documentation page in the App Services documentation <https://www.mongodb.com/docs/atlas/app-services/sync/error-handling/errors/> where we have historically maintained information about error messages. — Reply to this email directly, view it on GitHub <#2481 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAH2GP623CIPVCZVMRQQO2TWR4CBBANCNFSM6AAAAAATYIRQIM>. You are receiving this because you were mentioned.

[dacharyc]

I think it's true that there is summarization or consolidation going on - for example, I just put up a PR for a new page where I discovered we consolidate two different backend errors into one client error - but in looking around since your feedback here, I also see that our error documentation is out of date or incomplete in different places. I think that means we definitely need a larger project around this.

Meanwhile, I'll have a PR up shortly to link between the SDK docs and the App Services docs, so at least some of that information is available.

Again, thank you for raising this!