Exceptions

Authentication Error

You’ll receive an authentication exception if your API keys are incorrect. If getting this exception when first integrating, double-check that you didn’t accidentally try to use your sandbox keys in production or vice versa.

Authorization Error

You’ll receive an authorization exception if the API key that you’re using is not authorized to perform the attempted action according to the roles assigned to the user who owns the API key.

Down for Maintenance Error

You’ll receive a down for maintenance error if a request times out. We originally used this exception during maintenance windows, but we never go down for maintenance anymore. In a future release of the client library we’ll likely rename this, but we’re keeping the current name to maintain backwards compatibility for client side exception handling.

Forged Query String

You’ll receive this error if somebody hits your transparent redirect URL with an invalid hash in the query string.

The reason why this error happens is because when the Gateway receives the initial Transparent Redirect request, it generates a query string that includes a verification hash at the end to protect against tampering in the client. This hash is calculated based on the entire contents of the query string minus the hash. The client library uses the same method to check the hash, and so you’ll get this error any time the query string passed into the confirm method is not exactly the same as the query string that the Gateway redirected to.

Not Found Error

You’ll receive a not found exception when the record that you’re trying to operate on cannot be found. For example, if you try to update a customer and the customer ID isn’t valid. For references and associations, you’ll receive a validation error if the reference is invalid. For example, when creating a credit card and specifying which customer ID it should be associated to, if the customer ID is invalid, it will be a validation error, not a not found exception.

During TR Confirmation

If you are getting this error while using Transparent Redirect confirmation, then this is what is most likely happening:

  1. A user posts form directly to Braintree, which causes Braintree to create a Transparent Redirect Request in Braintree’s system
  2. Braintree redirects the user’s browser back to the passed redirect URL along with a token identifying the Transparent Redirect Request that Braintree created
  3. The code on the passed redirect URL grabs the query string and uses that token to ask Braintree for the response to the Transparent Redirect Request (this happens in the “confirm” method)
  4. Braintree receives the confirm request, which causes Braintree to consume the Transparent Redirect request and send you the response details.

If a user refreshes on your redirect URL page (or if they use the back button to return to it), your code might be calling the “confirm” method again with the same token, which has been already consumed by Braintree and so you get this error because the Transparent Redirect request cannot be found. The quick solution to prevent this from happening is to put the confirm call into a try/catch block to catch the exception that is thrown. This however can result in the form being re-rendered empty without any validation information, which–likely–the user will not enjoy very much. You might consider putting up a confirm dialog on refresh to make sure the user is aware that everything will get cleared, but still it’s not the ideal solution.

A more robust way of handling this is to store the all the params and validation errors in the user’s session as soon as you get them back from “confirm”, and then repopulate the form from that data instead of relying on the data coming directly from the confirm message, which will only return data once. Once you do that, you can either redirect the user again to a page where the validation errors are rendered from the data stored in the session, or you can just catch the exception and continue to render the form on the same page.

Server Error

You’ll receive a server error if something goes wrong on the server when trying to process your request.

SSL Certificate Error

You’ll receive an SSL certification error if the client library cannot verify the server’s SSL certificate. This may indicate an attempted man-in-the-middle attack.

Upgrade Required Error

You’ll receive this error if you’re trying to use a version of the library that is no longer supported. Note that the we support all client library versions that are in use and we will not deprecate an existing version without first reaching out to anyone who needs to upgrade.