> ## Documentation Index > Fetch the complete documentation index at: https://docs.fingerprint.com/llms.txt > Use this file to discover all available pages before exploring further. # Error handling > This page contains a reference for errors, timeouts, and other potential problems you can encounter while using the JavaScript agent. export const DeprecatedVersion = ({currentPath}) => This version is deprecated. See the{" "} deprecation policy and use the current version instead. ; If you are just getting started with Fingerprint, we recommend reading the following guides first: * [Install the JavaScript agent](/docs/install-the-javascript-agent) * [Identify visitors](/docs/identify-visitors) If this page does not help you troubleshoot your problem with the JavaScript agent, please contact our [support team](https://fingerprint.com/support/). ## Errors The JavaScript agent's [`load()`](/reference/v3/js-agent-load-function) and [`get()`](/reference/v3/js-agent-get-function) functions return a promise which will be rejected in case of an error. The table below summarizes the possible types of errors. | Error constant | Short description | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `FingerprintJS.ERROR_NETWORK_CONNECTION` | Connecting to the Fingerprint server failed. This is often caused by [ad blockers](/docs/protecting-the-javascript-agent-from-adblockers). Logged as `Network connection error`. | | `FingerprintJS.ERROR_NETWORK_ABORT` | Fingerprint server request is aborted. Logged as `Network request aborted`. | | `FingerprintJS.ERROR_API_KEY_MISSING` | Public API key is missing. Logged as `API key required`. | | `FingerprintJS.ERROR_API_KEY_INVALID` | Public API key is invalid. Logged as `API key not found`. | | `FingerprintJS.ERROR_API_KEY_EXPIRED` | Public API key is expired. Logged as `API key expired`. | | `FingerprintJS.ERROR_BAD_REQUEST_FORMAT` | Bad Fingerprint server request data. Can be caused by a wrong TLS endpoint. Logged as `Request cannot be parsed`. | | `FingerprintJS.ERROR_BAD_RESPONSE_FORMAT` | Bad Fingerprint server response data. Can be caused by a wrong endpoint. Logged as `Response cannot be parsed`. | | `FingerprintJS.ERROR_GENERAL_SERVER_FAILURE` | General request server-side failure. Logged as `Request failed`. | | `FingerprintJS.ERROR_CLIENT_TIMEOUT` | Client-side timeout. Logged as `Client timeout`. | | `FingerprintJS.ERROR_SERVER_TIMEOUT` | Server request times out. Logged as `Request failed to process`. | | `FingerprintJS.ERROR_RATE_LIMIT` | Request rate limit is exceeded. Logged as `Too many requests, rate limit exceeded`. | | `FingerprintJS.ERROR_FORBIDDEN_ORIGIN` | Identification request is blocked due to forbidden origin (see [Request filtering](/docs/request-filtering-for-websites)). Logged as `Not available for this origin`. | | `FingerprintJS.ERROR_FORBIDDEN_HEADER` | Identification request is blocked due to forbidden HTTP header (see [Request filtering](/docs/request-filtering-for-websites)). Logged as `Not available with restricted header`. | | `FingerprintJS.ERROR_NETWORK_RESTRICTED` | Identification request is blocked due to forbidden IP range (see [Network request filtering](/docs/network-request-filtering)). Logged as `Network restricted`. | | `FingerprintJS.ERROR_WRONG_REGION` | The [region](/docs/regions) set in the agent options doesn't match the region that was used to create your workspace. Logged as `Wrong region`. | | `FingerprintJS.ERROR_SUBSCRIPTION_NOT_ACTIVE` | Your workspace hasn't been activated in the dashboard. Logged as `Subscription not active`. | | `FingerprintJS.ERROR_UNSUPPORTED_VERSION` | The JavaScript agent version is not supported. Logged as `Unsupported version`. | | `FingerprintJS.ERROR_SCRIPT_LOAD_FAIL` | Failed to load the latest JavaScript agent code. Only available in the NPM installation method. This is often caused by [ad blockers](/docs/protecting-the-javascript-agent-from-adblockers). Logged as `Failed to load the JavaScript script of the agent`. | | `FingerprintJS.ERROR_INSTALLATION_METHOD_RESTRICTED` | The JavaScript agent installation method is not allowed. Logged as `Installation method restricted`. | | `FingerprintJS.ERROR_CSP_BLOCK` | Blocked by the [Content Security Policy](/docs/js-agent-csp) of the page. Logged as `Blocked by CSP`. | | `FingerprintJS.ERROR_INTEGRATION_FAILURE` | Failure on the [integration](/docs/v3/protecting-the-javascript-agent-from-adblockers) side. Logged as `Integration failed`. | | `FingerprintJS.ERROR_INVALID_ENDPOINT` | The given [endpoint](/reference/v3/js-agent-load-function#endpoint) is not a valid URL. Logged as `The endpoint parameter is not a valid URL`. | | `FingerprintJS.ERROR_INVALID_PROXY_INTEGRATION_SECRET` | The integration's proxy secret is missing, incorrect, or belongs to a different Fingerprint workspace than the public API key in the identification request. See to documentation of your proxy integration for more information. Logged as `Invalid proxy integration secret`. | | `FingerprintJS.ERROR_PROXY_INTEGRATION_SECRET_ENVIRONMENT_MISMATCH` | The integration's proxy secret is scoped to a [different environment](/docs/multiple-environments#proxy-integrations-and-proxy-secrets) than the public API key in the identification request. Logged as `Proxy integration secret environment mismatch`. | | `FingerprintJS.ERROR_INVALID_PROXY_INTEGRATION_HEADERS` | An unexpected implementation error or network misconfiguration of the proxy integration. Contact support for more information. Logged as `Invalid proxy integration headers`. | With the exception of `ERROR_CLIENT_TIMEOUT`, `ERROR_NETWORK_CONNECTION` `ERROR_NETWORK_ABORT`, `ERROR_SCRIPT_LOAD_FAIL` and `ERROR_CSP_BLOCK`, all the errors described above will include the [`requestId` field](/reference/v3/js-agent-get-function#requestid). The methods can also throw other unexpected errors, they should be treated as agent bugs. Error handling example: ```javascript Async/Await theme={"theme":"github-dark-dimmed"} const fpPromise = FingerprintJS.load({ /* ... */ }) try { const fp = await fpPromise const result = await fp.get() } catch (error) { switch (error.message) { case FingerprintJS.ERROR_GENERAL_SERVER_FAILURE: console.log('Unknown server error. Request id:', error.requestId) break case FingerprintJS.ERROR_CLIENT_TIMEOUT: console.log('Analysis time limit of 10 seconds is exceeded') break default: console.log('Other error') } } ``` ```javascript Promises theme={"theme":"github-dark-dimmed"} const fpPromise = FingerprintJS.load({ /* ... */ }) fpPromise .then(fp => fp.get()) .then(result => console.log(result.visitorId)) .catch(error => { switch (error.message) { case FingerprintJS.ERROR_GENERAL_SERVER_FAILURE: console.log('Unknown server error. Request id:', error.requestId) break case FingerprintJS.ERROR_CLIENT_TIMEOUT: console.log('Identification time limit of 10 seconds is exceeded') break default: console.log('Other error') } }) ``` ## Ad blockers Ad blockers can block identification requests or prevent the JavaScript agent from loading at all. This usually results in a `net::ERR_BLOCKED_BY_CLIENT` error in the console, accompanied by `Failed to load the JavaScript script of the agent` or `Network connection error`. We offer a variety of proxy integrations to avoid this issue. See [Protecting the JavaScript agent from ad blockers](/docs/protecting-the-javascript-agent-from-adblockers) for a list of solutions. ## Timeouts Two types of timeouts are possible: a **server** timeout and a **client** timeout. ### Server timeout The server timeout is fixed at 10 seconds of server-side processing time. If server-side processing exceeds 10 seconds for any reason, the promise will be rejected. ### Client timeout [Client timeout](/reference/v3/js-agent-get-function#timeout) controls the total time (both client-side and server-side) that any analysis event is allowed to run. By default, it's 10 seconds. Note that even if the client-side timeout is exceeded, the server-side request can still be running, and its results will be sent to you via a [webhook](/docs/v3/webhooks) if enabled. ## Rate limiting Every workspace API key has a rate limit. It means you cannot make more requests per second than your rate limit allows. See [Account limits](/docs/billing#account-limits) for more details. Whenever the rate limit is exceeded, the request is throttled and an `ERROR_RATE_LIMIT` error is thrown. ## Retrying after an error The JavaScript agent retries automatically in case of failure. If you want the agent to make more attempts, increase the [timeout](/reference/v3/js-agent-get-function#timeout). If you want to retry with another endpoint, set an array of endpoints in the JavaScript agent option (see options: [scriptUrlPattern](/reference/v3/js-agent-load-function#scripturlpattern), [endpoint](/reference/v3/js-agent-load-function#endpoint)). We don't recommend implementing your own retry mechanism around the JavaScript agent because it can lead to excessive consumption of paid API calls. ## TypeScript errors The JavaScript agent officially supports TypeScript **version 5.1** but may work with newer and older versions of TypeScript. If you face a TypeScript error in the `.d.ts` file provided by Fingerprint ([example 1](https://github.com/fingerprintjs/fingerprintjs/issues/651), [example 2](https://github.com/fingerprintjs/fingerprintjs/issues/653)), consider one of these solutions: ### Update TypeScript in your project (recommended) Update the TypeScript package in your project to version 5.1 or newer. ```bash NPM theme={"theme":"github-dark-dimmed"} npm install typescript@^5.1 ``` ```bash Yarn theme={"theme":"github-dark-dimmed"} yarn add typescript@^5.1 ``` ### Prevent TypeScript from using the library types In your TS files, import the minified ESM file directly: ```javascript JavaScript theme={"theme":"github-dark-dimmed"} import ... from '@fingerprintjs/fingerprintjs-pro' // [!code --] import ... from '@fingerprintjs/fingerprintjs-pro/dist/fp.esm.min' // [!code ++] ``` In your `.d.ts` file (if there is no such file, create one anywhere with any name), add the following line: ```typescript TypeScript theme={"theme":"github-dark-dimmed"} declare module '@fingerprintjs/fingerprintjs-pro/dist/fp.esm.min' ```