Add TypeScript types for Exceptions/Errors

[lambrospetrou]

Describe the issue with documentation

Right now when there is an error calling an API the error object is basically of type any, and therefore you get zero typing information and help from the IDEs.

Even on the documentation website it's suggesting to do string checks on the error.name property in order to see what kind of error it is, and then decide accordingly.

This makes it very to properly handle errors, especially when there are several possible failures. For example, in the s3.headObject operation the failure could be a 404 (name=NotFound) or a 403.

It would be great to have concrete type definitions for TypeScript that is easy to use the error responses, similar to the happy case with XxxCommandInput/Output types.

Right now basically we have to check the API documentation for each operation used, e.g. API Head Object, to see what errors, or how they will probably be named.

Thanks

[AdonousTech]

+1
What happened to the AWSError type? Below is what it used to be in V2, but I can't find it anywhere in V3 API.

/**
 * A structure containing information about a service or networking error.
 */
export class AWSError extends Error {
    /**
     * A unique short code representing the error that was emitted.
     */
    code: string;
    /**
     * A longer human readable error message.
     */
    message: string;
    /**
     * Whether the error message is retryable.
     */
    retryable: boolean;
    /**
     * In the case of a request that reached the service, this value contains the response status code.
     */
    statusCode: number;
    /**
     * The date time object when the error occurred.
     */
    time: Date;
    /**
     * Set when a networking error occurs to easily identify the endpoint of the request.
     */
    hostname: string;
    /**
     * Set when a networking error occurs to easily identify the region of the request.
     */
    region: string;
    /**
     * Amount of time (in seconds) that the request waited before being resent.
     */
    retryDelay: number;
    /**
     * The unique request ID associated with the response.
     */
    requestId: string;
    /**
     * Second request ID associated with the response from S3.
     */
    extendedRequestId: string;
    /**
     * CloudFront request ID associated with the response.
     */
    cfId: string;
}

[rdmurphy]

Throwing a +1 on this as well — I was very surprised to see that err.code disappeared which we had many things depending on. I'm cool with changes of course! But does feel like a step back.

[trivikr]

Related #1506

[abierbaum]

Until this is resolved I don't see any clear way to handle errors. Has anyone found a pattern that works well here?

[ScriptSmith]

The error types have changed in v3. The closest thing to the old AWSError type is SdkError.

// Note this is a TS type only, not an Error object
import { SdkError } from "@aws-sdk/types";

It inherits from Error + partially from SmithyException and MetadataBearer
Documentation link

It has the following properties:

type SdkError = {
  /**
   * Name, eg. ConditionalCheckFailedException
   */
  name: string;

  /**
   * Human-readable error response message
   */
  message: string;

  /**
   * Non-standard stacktrace
   */
  stack?: string;

  /**
   * Whether the client or server are at fault.
   */
  readonly $fault?: "client" | "server";

  /**
   * The service that encountered the exception.
   */
  readonly $service?: string;

  /**
   * Indicates that an error MAY be retried by the client.
   */
  readonly $retryable?: {
    /**
     * Indicates that the error is a retryable throttling error.
     */
    readonly throttling?: boolean;
  };

  $metadata?: {
    /**
     * The status code of the last HTTP response received for this operation.
     */
    httpStatusCode?: number;

    /**
     * A unique identifier for the last request sent for this operation. Often
     * requested by AWS service teams to aid in debugging.
     */
    requestId?: string;

    /**
     * A secondary identifier for the last request sent. Used for debugging.
     */
    extendedRequestId?: string;

    /**
     * A tertiary identifier for the last request sent. Used for debugging.
     */
    cfId?: string;

    /**
     * The number of times this operation was attempted.
     */
    attempts?: number;

    /**
     * The total amount of time (in milliseconds) that was spent waiting between
     * retry attempts.
     */
    totalRetryDelay?: number;
  };
};

However, note that in TS you cannot narrow the type of the exception parameter in a try...catch statement anyway:

try {
  await client.send(...)
} catch (e: SdkError) {
  // TS1196: Catch clause variable type annotation must be 'any' or 'unknown' if specified.
  console.log(error.$metadata.httpStatusCode);
}

You can narrow the reason in a Promise.catch, but this is not a guard and strictly speaking there is no way in TS to indicate or guarantee the possible errors at compile-time, so IDEs can't really help you unless the errors tagged are in the docs.

client
  .send(
    ...
  )
  .then((result) => ({
    status: "success",
    result,
  }))
  .catch((error: SdkError) => {
    if (error.name == "ResourceNotFoundException") {
      return {
        status: "missing",
      };
    } else {
      throw error;
    }
  });

To have compile-time guarantees about possible errors, you could use the AWS SDK for a different language like the Rust SDK, which has a strict Result type you can use match expressions on:

let client = aws_sdk_dynamodb::Client::from_env();
let req = client.query()
    .table_name("my_table")
    .key_condition_expression("...")
    .limit(10);

match req.send().await {
    Ok(response) => response.items.iter().for_each(|item| println!("Item: {:#?}", item)),
    Err(SdkError::ServiceError { err, .. }) => match err.kind {
        QueryErrorKind::ProvisionedThroughputExceededError(_) => eprintln!("Not enough throughput"),
        QueryErrorKind::RequestLimitExceeded(_) => eprintln!("Too many requests"),
        QueryErrorKind::ResourceNotFoundError(_) => eprintln!("Failed to find resource"),
        e => eprintln!("Internal error: {:#?}", e)
    }
    Err(e) => eprintln!("Client error: {:#?}", e)
}

[dmattia]

You can use type-guards in typescript like:

/**
 * Checks if an object is an RejectedRecordsException
 *
 * @param err - error object to check the type of
 * @returns true if the object is a RejectedRecordsException
 */
function isRejectedRecordsException(err: any): err is RejectedRecordsException {
  return err?.name === 'RejectedRecordsException';
}

Then running code like:

    const currentTime = Date.now();
    try {
      await timestreamClient.send(
        new WriteRecordsCommand({
          DatabaseName: 'someDb',
          TableName: 'someTable',
          CommonAttributes: {
            MeasureName: 'test',
            MeasureValue: `20`,
            Time: `${currentTime}`,
            Dimensions: [{ Name: 'testDim', Value: 'foobar' }],
          },
          Records: [
            {
              TimeUnit: TimeUnit.MILLISECONDS,
            },
            {
              TimeUnit: TimeUnit.NANOSECONDS,
            },
          ],
        }),
      );
    } catch (e) {
      if (isRejectedRecordsException(e)) {
        logger.error(JSON.stringify(e.RejectedRecords));
      }
    }

works nicely, as e is of type RejectedRecordsException inside the if clause.

Maybe this SDK could export a similar set of type assertion functions, one for each exception?

[ScriptSmith]

Good point.

There are some existing functions that aren't type guards, but perhaps could be: https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_service_error_classification.html#istransienterror

But I think having type guards for each service's errors would be useful.

[iccicci]

I red somebody complaining about the code property replaced with name one; IMHO that's not a problem, a major version change usually means the lack of backward compatibility.

I red about writing our own type guard functions, but I feel it is a bad idea: we have no guarantee that the SDK will not change someway to break our functions.

In general, throwing something which is not an instance (better if of a class extending the native Error one) is a bad idea: we can't use the native instanceof operator (neither the stack property)!

Honestly I would expect from the AWS SDK v3 the same high quality standard that we have from any other AWS service.

[jhunterkohler]

@iccicci I agree with you. My error handling currently depends on guessing what the error type is by the name property and the metadata property. I think most issues would be solved by presenting a wrapper around every SDK error so we can differentiate that by the instanceof. But, that relies on the more documentation for the error structure (which I've yet to find, found this while searching).

[tlm-daniele-ricci]

I do not pretend a so heavy refactoring to let us using the instanceof operator.

Thrown errors are already interfaces... I think we could tolerate that if we had a type guard function for each SDK error.

[jhunterkohler]

@tlm-daniele-ricci I realize you're right. instanceof really isn't that useful. I think people are just confused because they can't find a list of error names and such.