Export RestError, AbortError, TimeoutError, and ErrorResponse. (Azure#24373)

* Export RestError, AbortError, and TimeoutError

* Convert ErrorResponse interface to class

* Add Error handling section in README

* Fix formatting

Co-authored-by: Aman Rao <[email protected]>

Author: amanrao23

sdk/cosmosdb/cosmos/README.md

@@ -183,6 +183,36 @@ for (const city of resources) {
 
 For more information on querying Cosmos DB databases using the SQL API, see [Query Azure Cosmos DB data with SQL queries][cosmos_sql_queries].
 
+## Error Handling
+
+The SDK generates various types of errors that can occur during an operation.
+
+1. `ErrorResponse` is thrown if the response of an operation returns an error code of >=400.
+2. `TimeoutError` is thrown if Abort is called internally due to timeout.
+3. `AbortError` is thrown if any user passed signal caused the abort.
+4. `RestError` is thrown in case of failure of underlying system call due to network issues.
+5. Errors generated by any devDependencies. For Eg. `@azure/identity` package could throw `CredentialUnavailableError`.
+
+Following is an example for handling errors of type `ErrorResponse`, `TimeoutError`, `AbortError`, and `RestError`.
+
+```js
+try {
+  // some code
+} catch (err) {
+  if (err instanceof ErrorResponse) {
+    // some specific error handling.
+  } else if (err instanceof RestError) {
+    // some specific error handling.
+  }
+  // handle other type of errors in similar way.
+  else {
+    // for any other error.
+  }
+}
+```
+
+It's important to properly handle these errors to ensure that your application can gracefully recover from any failures and continue functioning as expected. More details about some of these errors and their possible solutions can be found [here]<!--(https://learn.microsoft.com/azure/cosmos-db/nosql/conceptual-resilient-sdk-applications#should-my-application-retry-on-errors)-->.
+
 ## Troubleshooting
 
 ### General

sdk/cosmosdb/cosmos/package.json

@@ -102,7 +102,8 @@
     "semaphore": "^1.0.5",
     "tslib": "^2.2.0",
     "universal-user-agent": "^6.0.0",
-    "uuid": "^8.3.0"
+    "uuid": "^8.3.0",
+    "@azure/abort-controller": "^1.0.0"
   },
   "devDependencies": {
     "@azure/dev-tool": "^1.0.0",

sdk/cosmosdb/cosmos/review/cosmos.api.md

@@ -7,10 +7,14 @@
 /// <reference lib="dom" />
 /// <reference lib="esnext.asynciterable" />
 
+import { AbortError } from '@azure/abort-controller';
 import { AbortSignal as AbortSignal_2 } from 'node-abort-controller';
 import { Pipeline } from '@azure/core-rest-pipeline';
+import { RestError } from '@azure/core-rest-pipeline';
 import { TokenCredential } from '@azure/core-auth';
 
+export { AbortError }
+
 // @public (undocumented)
 export interface Agent {
     // (undocumented)
@@ -704,7 +708,7 @@ export interface ErrorBody {
 }
 
 // @public (undocumented)
-export interface ErrorResponse extends Error {
+export class ErrorResponse extends Error {
     // (undocumented)
     [key: string]: any;
     // (undocumented)
@@ -1552,6 +1556,8 @@ interface Response_2<T> {
 }
 export { Response_2 as Response }
 
+export { RestError }
+
 // @public
 export interface RetryOptions {
     fixedRetryIntervalInMilliseconds: number;
@@ -1858,6 +1864,13 @@ export class StoredProcedures {
 // @public (undocumented)
 export type SubStatusCode = number;
 
+// @public (undocumented)
+export class TimeoutError extends Error {
+    constructor(message?: string);
+    // (undocumented)
+    readonly code: string;
+}
+
 // @public
 export class TimeSpan {
     constructor(days: number, hours: number, minutes: number, seconds: number, milliseconds: number);

sdk/cosmosdb/cosmos/src/index.ts

@@ -85,3 +85,5 @@ export { ClientContext } from "./ClientContext";
 export { GlobalEndpointManager } from "./globalEndpointManager";
 export { SasTokenPermissionKind } from "./common/constants";
 export { createAuthorizationSasToken } from "./utils/SasToken";
+export { RestError } from "@azure/core-rest-pipeline";
+export { AbortError } from "@azure/abort-controller";

sdk/cosmosdb/cosmos/src/request/ErrorResponse.ts

@@ -55,7 +55,7 @@ export interface GroupByAliasToAggregateType {
   [key: string]: AggregateType;
 }
 
-export interface ErrorResponse extends Error {
+export class ErrorResponse extends Error {
   code?: number;
   substatus?: number;
   body?: ErrorBody;

sdk/cosmosdb/cosmos/src/request/RequestHandler.ts

@@ -106,7 +106,7 @@ async function httpRequest(requestContext: RequestContext): Promise<{
     : undefined;
 
   if (response.status >= 400) {
-    const errorResponse: ErrorResponse = new Error(result.message);
+    const errorResponse: ErrorResponse = new ErrorResponse(result.message);
 
     logger.warning(
       response.status +

sdk/cosmosdb/cosmos/src/request/index.ts

@@ -18,3 +18,4 @@ export { SharedOptions } from "./SharedOptions";
 export { StatusCode, SubStatusCode } from "./StatusCodes";
 export { FeedResponse } from "./FeedResponse";
 export { RequestContext } from "./RequestContext";
+export { TimeoutError } from "./TimeoutError";