apify-client 3.0.0-beta.5 → 3.0.0-beta.7

package/README.md

@@ -47,7 +47,9 @@ Besides greatly simplifying the process of querying the Apify API, the client pr
 Based on the endpoint, the client automatically extracts the relevant data and returns it in the
 expected format. Date strings are automatically converted to `Date` objects. For exceptions,
 we throw an `ApifyApiError`, which wraps the plain JSON errors returned by API and enriches
-them with other context for easier debugging.
+them with other context for easier debugging. The error is an instance of the subclass matching the
+HTTP status code, such as `NotFoundError` or `RateLimitError`, so a `catch` block can tell them apart
+with `instanceof`.
 
 ### Retries with exponential backoff
 

package/dist/apify_api_error.d.ts

@@ -1,10 +1,20 @@
 import type { AxiosResponse } from 'axios';
+import type { LiteralUnion } from 'type-fest';
+import type { ApifyApiErrorType } from './models.js';
+export type { ApifyApiErrorType } from './models.js';
 /**
  * An `ApifyApiError` is thrown for successful HTTP requests that reach the API,
  * but the API responds with an error response. Typically, those are rate limit
  * errors and internal errors, which are automatically retried, or validation
  * errors, which are thrown immediately, because a correction by the user is
  * needed.
+ *
+ * The thrown error is an instance of the subclass matching the HTTP status code of the response:
+ * {@link InvalidRequestError} (400), {@link UnauthorizedError} (401), {@link ForbiddenError} (403),
+ * {@link NotFoundError} (404), {@link ConflictError} (409), {@link RateLimitError} (429) or
+ * {@link ServerError} (5xx). Any other status code is thrown as a plain `ApifyApiError`. Every
+ * subclass extends `ApifyApiError`, so `instanceof ApifyApiError` matches all of them. Errors that
+ * share a status code are told apart by their `type`.
  */
 export declare class ApifyApiError extends Error {
     name: string;
@@ -18,9 +28,10 @@ export declare class ApifyApiError extends Error {
      */
     statusCode: number;
     /**
-     * The type of the error, as returned by the API.
+     * The type of the error, as returned by the API. Typed as the known {@link ApifyApiErrorType}
+     * values for autocompletion, while still accepting any string the API may return.
      */
-    type?: string;
+    type?: LiteralUnion<ApifyApiErrorType, string>;
     /**
      * Number of the API call attempt.
      */
@@ -46,6 +57,11 @@ export declare class ApifyApiError extends Error {
      * @hidden
      */
     constructor(response: AxiosResponse, attempt: number);
+    /**
+     * Creates the error for a failed response as an instance of the subclass matching its HTTP status code.
+     * @hidden
+     */
+    static fromResponse(response: AxiosResponse, attempt: number): ApifyApiError;
     private _safelyParsePathFromResponse;
     private _extractClientAndMethodFromStack;
     /**
@@ -54,7 +70,7 @@ export declare class ApifyApiError extends Error {
      *
      * Example:
      *
-     * ApifyApiError: Actor task was not found
+     * NotFoundError: Actor task was not found
      *   clientMethod: TaskClient.start
      *   statusCode: 404
      *   type: record-not-found
@@ -64,3 +80,43 @@ export declare class ApifyApiError extends Error {
      */
     private _createApiStack;
 }
+/**
+ * Thrown when the Apify API responds with HTTP 400 Bad Request, typically because the request
+ * failed validation.
+ */
+export declare class InvalidRequestError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 401 Unauthorized, because the token is missing
+ * or invalid.
+ */
+export declare class UnauthorizedError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 403 Forbidden, because the token lacks the
+ * permission for the operation.
+ */
+export declare class ForbiddenError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 404 Not Found.
+ */
+export declare class NotFoundError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 409 Conflict.
+ */
+export declare class ConflictError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 429 Too Many Requests. The client retries such
+ * requests, so the error surfaces once the retries are exhausted.
+ */
+export declare class RateLimitError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with an HTTP 5xx status. The client retries such requests,
+ * so the error surfaces once the retries are exhausted.
+ */
+export declare class ServerError extends ApifyApiError {
+}

package/dist/apify_api_error.js

@@ -16,6 +16,13 @@ const CLIENT_METHOD_REGEX = /at( async)? ([A-Za-z]+(Collection)?Client)\._?([A-Z
  * errors and internal errors, which are automatically retried, or validation
  * errors, which are thrown immediately, because a correction by the user is
  * needed.
+ *
+ * The thrown error is an instance of the subclass matching the HTTP status code of the response:
+ * {@link InvalidRequestError} (400), {@link UnauthorizedError} (401), {@link ForbiddenError} (403),
+ * {@link NotFoundError} (404), {@link ConflictError} (409), {@link RateLimitError} (429) or
+ * {@link ServerError} (5xx). Any other status code is thrown as a plain `ApifyApiError`. Every
+ * subclass extends `ApifyApiError`, so `instanceof ApifyApiError` matches all of them. Errors that
+ * share a status code are told apart by their `type`.
  */
 export class ApifyApiError extends Error {
     name;
@@ -29,7 +36,8 @@ export class ApifyApiError extends Error {
      */
     statusCode;
     /**
-     * The type of the error, as returned by the API.
+     * The type of the error, as returned by the API. Typed as the known {@link ApifyApiErrorType}
+     * values for autocompletion, while still accepting any string the API may return.
      */
     type;
     /**
@@ -100,6 +108,14 @@ export class ApifyApiError extends Error {
         this.stack = this._createApiStack();
         this.data = errorData;
     }
+    /**
+     * Creates the error for a failed response as an instance of the subclass matching its HTTP status code.
+     * @hidden
+     */
+    static fromResponse(response, attempt) {
+        const ErrorClass = ERROR_CLASS_BY_STATUS[response.status] ?? (response.status >= 500 ? ServerError : ApifyApiError);
+        return new ErrorClass(response, attempt);
+    }
     _safelyParsePathFromResponse(response) {
         const urlString = response.config?.url;
         let url;
@@ -123,7 +139,7 @@ export class ApifyApiError extends Error {
      *
      * Example:
      *
-     * ApifyApiError: Actor task was not found
+     * NotFoundError: Actor task was not found
      *   clientMethod: TaskClient.start
      *   statusCode: 404
      *   type: record-not-found
@@ -145,3 +161,51 @@ export class ApifyApiError extends Error {
         return `${name}: ${this.message}\n${stack}`;
     }
 }
+/**
+ * Thrown when the Apify API responds with HTTP 400 Bad Request, typically because the request
+ * failed validation.
+ */
+export class InvalidRequestError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 401 Unauthorized, because the token is missing
+ * or invalid.
+ */
+export class UnauthorizedError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 403 Forbidden, because the token lacks the
+ * permission for the operation.
+ */
+export class ForbiddenError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 404 Not Found.
+ */
+export class NotFoundError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 409 Conflict.
+ */
+export class ConflictError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 429 Too Many Requests. The client retries such
+ * requests, so the error surfaces once the retries are exhausted.
+ */
+export class RateLimitError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with an HTTP 5xx status. The client retries such requests,
+ * so the error surfaces once the retries are exhausted.
+ */
+export class ServerError extends ApifyApiError {
+}
+const ERROR_CLASS_BY_STATUS = {
+    400: InvalidRequestError,
+    401: UnauthorizedError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    429: RateLimitError,
+};