错误处理

印象笔记云 API 的错误类型和常见原因

错误类型

云 API 返回三种类型的错误。云 API 封装库通过抛出异常的方式来报错。每个 API 调用的参考文档列出了抛出异常的准确原因。

当 API 的调用者输入了错误的参数时，将抛出 EDAMUserException 异常。这类异常可以在调用的应用中解决。例如，当使用一个过期的认证 token 时，就会抛出一个 EDAMUserException。如果要确定产生错误的具体原因，请查看 errorCode 和异常中的参数值。

印象笔记 web 服务的内部错误会造成抛出 EDAMSystemException 异常。这类异常没有办法在调用的应用中解决。如果要确定产生错误的具体原因，请查看 errorCode 和异常中的参数值。

当 API 调用所请求的数据对象不存在时，将抛出 EDAMNotFoundException 异常。例如，当使用一个用户帐户内不存在的 GUID 来调用 NoteStore.getNote 时，会抛出 EDAMNotFoundException 异常。

常见错误情况

在使用云 API 时，你应当确保你正确地处理了如下的错误情况：

认证失败

当进行 NoteStore 调用的时候，有一些原因可以造成认证失败。在这种情况下，会抛出一个 EDAMUserException 异常。这个异常包含错误代码和指示了失败原因的参数。你应该检查并处理如下的错误代码：

• AUTH_EXPIRED - 认证 token 过期了。在进行任何 NoteStore 调用之前，你需要重新认证并获取一个新的认证 token。
• PERMISSION_DENIED - 认证 token 包含的权限不足以调用当前的 API。你必须联系我们的开发者支持团队来扩展你的 API 权限，否则你的应用将不能进行这个请求操作。

超出流量限制

印象笔记 web 服务限制了每个用户在每个月可以上传到他们帐户的数据的大小。如果用户的剩余流量不足以完成请求的操作，那么 NoteStore.createNote 和 NoteStore.updateNote 的调用将失败。在这种情况下，会抛出一个带有错误代码 QUOTA_EXCEEDED 的 EDAMUserException 异常。

当你的应用到达了用户的流量限制时，应用应当告知用户他们已经达到了每月的流量限制，所以他们不能创建或更新所请求的笔记。使用免费印象笔记帐户的用户可以通过升级到印象笔记高级版来获取更多的流量。高级版帐户可以通过购买一次性的流量来解决问题（印象笔记服务暂时不支持一次性的流量购买）。这些操作要通过印象笔记 web 应用来进行，而不能在你的应用里面发起。

你可以通过云 API 来确定用户的服务级别（免费版或高级版）、每月的总上传流量、剩余流量、和流量恢复日期：

Maximum note size

印象笔记 web 服务限制了单个笔记的大小。如果笔记最新的大小超出了最大的限制，那么 NoteStore.createNote 和 NoteStore.updateNote 的调用将会失败。在这种情况下，会抛出一个带有错误代码 LIMIT_REACHED 的 EDAMUserException 异常。

免费版用户和高级版用户的笔记大小限制是不同的。目前，免费版用户的笔记大小限制是 25MB，而高级版用户的笔记大小限制是 50MB。但是你的应用不应当把这些值硬编码在代码中，因为我们可能会改变这些值。相反，你应当使用云 API 封装库中的 EDAM_NOTE_SIZE_MAX_FREE 和 EDAM_NOTE_SIZE_MAX_PREMIUM 常量值。

你的应用应当在创建和更新笔记之前检查笔记的大小不要超出大小限制。笔记的大小包括笔记内容中的 unicode 字符的数目，还包括所有附加的资源大小。在实践中，通常检查附加的资源大小就足够了。