Error handling

ArcGIS REST JS exposes four classes to represent different types of errors you may encounter when using ArcGIS services.

Class	Description
`ArcGISRequestError`	A general error response from an ArcGIS service REST endpoint.
`ArcGISAuthError`	An invalid token.
`ArcGISAccessDeniedError`	Occurs when a user cancels or denies an OAuth 2.0 authorization request.
`ArcGISTokenRequestError`	Occurs when `ArcGISIdentityManager` or `ApplicationCredentialsManager` fails to refresh a token or to generate a new token for a request.

Example

This example demonstrates how to handle all four error types

Use dark colors for code blocksCopy
import { request, ErrorTypes } from "@esri/arcgis-rest-request";

request(url, {
  authentication: authenticationManager
})
  .then(response => {
    console.log(response);
  }).catch(e => {
    switch(e.name) {
      case ErrorTypes.ArcGISRequestError:
        // handle a general error from the API
      break;

      case ErrorTypes.ArcGISAuthError:
        // handle an authentication error
      break;

      case ErrorTypes.ArcGISAccessDeniedError:
        // handle a user denying an authorization request in an oAuth workflow
      break;

      case ErrorTypes.ArcGISTokenRequestError:
        // handle an error response trying to generate a new access token
      break;

      default:
        // handle some other error (usually a network error)
   }
  });

Request errors

The base error type in ArcGIS REST JS is ArcGISRequestError, which extends the native Error object. ArcGISRequestError add several additional properties that contain the full response from the server, the original request URL, and the options of the request.

Use dark colors for code blocksCopy
request(url, {
  authentication: authenticationManager
})
  .then(response => {
    console.log(response);
  }).catch(e => {
    console.log(e.name);
    console.log(e.message);
   }
  });

Invalid token errors

If ArcGIS REST JS encounters an "invalid token" response from a service, an ArcGISAuthError will be thrown. ArcGISAuthError has an additional retry() method that allows you to pass in a new authentication manager to attempt the request again.

If the authentication manager cannot refresh the token successfully a generate token error will be thrown instead.

Access denied errors

If a user denies a request for authorization in the OAuth authorization window, an ArcGISAccessDeniedError will be thrown. This error is only thrown from the ArcGISIdentityManager.beginOAuth2() and ArcGISIdentityManager.completeOAuth2() methods.

Use dark colors for code blocksCopy
import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";

ArcGISIdentityManager.beginOAuth2({
  clientId: "YOUR_CLIENT_ID"
  redirectUri: "YOUR_REDIRECT_URI"
}).then(manager => {
  console.log("user authorized your application");
}).catch(e => {
  if(e.name === "ArcGISAccessDeniedError") {
    console.log("the user denied your request")
  }
})

Generate token errors

ArcGISIdentityManager and ApplicationCredentialsManager automatically manage the lifecycle of the token they are responsible for. Most of the time, the token generation is automatic and successful, but sometimes there are errors which is when ArcGISTokenRequestError is thrown.

There are several different error codes for ArcGISTokenRequestError described in ArcGISTokenRequestErrorCodes.

Use dark colors for code blocksCopy
request(someUrl, {
  authentication: someAuthenticationManager
}).catch(e => {
  if(e.name === "ArcGISTokenRequestError") {
    // ArcGIS REST JS could not generate an appropriate token for this request.
    // All credentials are likely invalid and the authentication process should be restarted.
  }
})

Unable to federate with ArcGIS Server

ArcGISTokenRequestError will also be thrown if you are using an ArcGIS Server portal and make a request to a service that is not federated with that portal.

The credentials in the authentication manager used for the failed request are likely still valid, but they cannot be used to make the request.

Use dark colors for code blocksCopy
import { request, ArcGISIdentityManager } from "@esri/arcgis-rest-request";
import { getService } from '@esri/arcgis-rest-feature-service';

ArcGISIdentityManager.beginOAuth2({
  clientId: "•••"
  redurectUri: "•••",
  portal: "https://my-organziation.com/my-arcgis-portal/"
}).then(manager => {
  // get information about a private service
  getService("https://other-organization/arcgis/rest/services/ExampleService/FeatureServer/", {
    authentication: manager
  })
  .then((info)=>{
    // If the server is federated with the portal the authentication
    // will be used and the request will be successful
  })
  .catch((e)=>{
    // otherwise we can check to see if this is a not federated error.
    // potentially this could be used to prompt the user to sign into
    // the appropriate portal.
    if(e.name === "ArcGISAuthError" && e.code === "NOT_FEDERATED") {

    }
  })
})