Skip to main content

Error Handling

When making requests to the Stitch Token API endpoints, you'll interact with a REST-style API for authentication.

As such, you can expect conventional HTTP response codes to indicate failures, with a 400 Bad Request HTTP status code and a JSON body containing the specific error message. All token API errors detailed in this section are synchronous.

Invalid Redirect URL​

{
  "redirect_uri": [
    "Invalid redirect_uri. Please ensure the URI has been whitelisted."
  ]
}

This error may be encountered when using a URL that has not been whitelisted for your client. To fix this, please use a valid whitelisted URL. Refer to your client credential JSON file for the list of valid, whitelisted URLs.

Please note that we do not allow wildcard URLs or URL with dynamic parameters - URLs need to be specific. We do, however, allow deep-linking for mobile applications.

To whitelist new URLs, please reach out to our support engineers with the URLs you wish to be added to your client.

Invalid Scope​

{
  "error": "invalid_scope"
}

This error may be encountered when trying to retrieve a client or user token, for one of the following reasons:

  • The scope parameter includes scopes not authorised for your client. You can verify the list of authorised scopes in your credential JSON file under the key allowedScopes. Should you require any additional scopes to be enabled, please reach out to our support engineers.
  • The scope parameter includes misspelled scopes.
  • The scope parameter is not included in the request.
  • If requesting for multiple scopes, the scope parameter has values not separated by a single whitespace, e.g. a valid value is client_paymentrequest client_refund.

Invalid Grant​

{
  "error": "invalid_grant"
}

This error may be encountered when trying to retrieve a client or user token, for one of the following reasons:

  • Retrieving a client token without specifying the scope parameter in the request parameters.
  • Retrieving a client token without specifying the invalid_grant parameter in the request parameters.
  • Retrieving a user token with a code_verifier value that's too short or too long. The value of both the code_verifier and code_challenge must be between 43 and 128 characters.
  • Retrieving a user token with a code_verifier and code_challenge pair that do not match. You can use the widget here to validate if the pairs match.
  • Using an expired authorization_code to fetch a user token. Authorization codes are single-use and have a lifetime of 5 minutes. Should the code expire before you can use it, you will need to re-initiate the linking process.

Invalid Code Challenge​

{
  "invalid_request": ["Invalid code_challenge"]
}

This error may occur when trying to generate an account authorization URL with an incorrectly-encoded value for the code_challenge parameter. To resolve this, ensure the code challenge is being encoded in base64URL encoding (not base64).