Troubleshooting Web Protection Errors
The Approov web SDK's fetchToken function normally responds with a valid or invalid Approov token. However, if there is a problem with a request that prevents the normal web protection handler from completing, then an error response will be generated. Also, if the underlying calls to the integrated protection APIs fail with an error, then this error is propagated to the response instead of generating failed tokens.
In these cases an error object is thrown from the fetchToken function:
| Error Type | Description |
|---|---|
ApproovError | Subclass of Error, base for any specific error type thrown during any Approov web SDK call. |
ApproovSessionError | The Approov session has not been initialized or has expired. If this occurs, a call to Approov.initializeSession()
should be made to refresh the session. |
ApproovFetchError | This wraps any error thrown by the fetch call made to perform a request to the Approov service. This
indicates that there was a communication or network issue when contacting the Approov service. The cause is
available in the errors property of the ApproovFetchError object. |
ApproovServiceError | This represents an error reported by the Approov service, such as missing or malformed elements in the underlying
request. The errors property of the ApproovServiceError object contains more information
about the error, which can be useful for debugging. The possible error codes and descriptions are listed below. |
For ApproovServiceError, the JSON object contains a sequence of key-value pairs, with the key indicating the type of error and the value providing extra information where appropriate. For some error types the value is just the empty string:
ApproovServiceError
{
"message": "<response-status-text>",
"errors": {
"<error-code-1>": "<further-details>",
"<error-code-2>": "",
...
}
}
An attempt is made to batch all problems with a request into the single error object to help make debugging quicker, however, this isn't always possible. The following table lists the error keys with a description of their cause. Any extra data provided in the associated value may aid debugging.
| Error Code | Description |
|---|---|
rqst-body-read-fail | There was a problem reading the request body. |
rqst-params-in-body-and-path | The request contains parameters in the URL and in the message body; this is not permitted. |
rqst-body-too-large | The request message body is too large. |
rqst-body-parse | The request message body could not be decoded; it's probably not formatted correctly. |
rqst-illegal-params | The request included illegal parameters; the list of illegal entries is included in the value. |
aprv-no-site-key | Your Approov site key was not included in the request parameters. |
aprv-no-web-protect-params | The request didn't contain any web protection parameters; no parameters for Fingerprint, hCaptcha, or reCAPTCHA. |
aprv-no-matching-account | The specified Approov site key didn't match any account. |
aprv-no-web-protect-def | The specified Approov site key doesn't have any web protection integrations defined. |
aprv-payload-param-invalid-size | The request has a payload parameter, but it has an invalid size (32 bytes when decoded). It must be a Base64URL encoded SHA256 hash, see Web Protection Token Binding. |
aprv-payload-not-b64url | The request has a payload parameter, but it isn't Base64URL encoded. It must be a Base64URL encoded SHA256 hash, see Web Protection Token Binding. |
aprv-api-no-targets | The request parameters don't include any api target. |
aprv-api-empty-target | The request parameters include an api target whose value is the empty string. |
aprv-api-duplicate-target | The request parameters include more than one api entry with the same value. |
aprv-api-too-many-targets | The request parameters include more api targets than there are APIs defined for the target account. |
aprv-api-not-found | One or more api targets are not defined in your Approov account. |
aprv-api-not-web-enabled | One or more api targets have not been web enabled. |
aprv-invalid-nonce | The nonce required for the request is missing, malformed, not signed correctly or expired. |
aprv-invalid-dpop-token | The DPoP token header is missing, or the received DPoP token is malformed, not signed correctly or expired. |
aprv-invalid-refresh-token | The refresh token is missing, malformed, not signed correctly or expired. |
fp-config-not-found | Fingerprint parameters were used in the request but no Fingerprint subscriptions are defined for the account. |
fp-missing-required-params | The request doesn't have Fingerprint parameters, but a Fingerprint check is required by the account, see the section on Fingerprint configuration. |
fp-param-mismatch | Some of the parameters for a Fingerprint check are specified but others are missing. |
fp-empty-browser-tok | A request with Fingerprint parameters has the Fingerprint public API key parameter set to the empty string. |
fp-empty-vis-id | A request with Fingerprint parameters has the visitor ID parameter set to the empty string. |
fp-empty-rqst-id | A request with Fingerprint parameters has the request ID parameter set to the empty string. |
fp-browser-tok-not-found | The Fingerprint public API key specified in a request doesn't match any defined in the selected Approov account. |
fp-tok-check | There was an error performing the Fingerprint server-side check; the error string is included in the value. |
hcap-config-not-found | hCaptcha parameters were used in the request but no hCaptcha Sites are defined for the account. |
hcap-missing-required-params | The request doesn't have hCaptcha parameters, but an hCaptcha check is required by the account settings, see the section on hCaptcha configuration. |
hcap-param-mismatch | Some of the parameters for an hCaptcha check are specified but others are missing. |
hcap-empty-site-key | A request has an hCaptcha site key parameter set to the empty string. |
hcap-empty-token | A request has an hCaptcha token parameter set to the empty string. |
hcap-site-key-not-found | The hCaptcha Site key specified in a request doesn't match any defined in the selected Approov account. |
hcap-token-check | There was an error performing the hCaptcha server-side check; the error string is included in the value. |
recap-config-not-found | reCAPTCHA parameters were used in the request but no reCAPTCHA Sites are defined for the account. |
recap-missing-required-params | The request doesn't have reCAPTCHA parameters, but a reCAPTCHA check is required by the account settings, see the section on reCAPTCHA configuration. |
recap-param-mismatch | Some of the parameters for a reCAPTCHA check are specified but others are missing. |
recap-empty-site-key | A request has a reCAPTCHA site key parameter set to the empty string. |
recap-empty-token | A request has a reCAPTCHA token parameter set to the empty string. |
recap-site-key-not-found | The reCAPTCHA Site key specified in a request doesn't match any defined in the selected Approov account. |
recap-token-check | There was an error performing the reCAPTCHA server-side check; the error string is included in the value. |