Exceptionsanchor

note

Some of our exceptions may be indicators of a known issue with Braintree's API. To stay up-to-date with any current issues or scheduled maintenance, we recommend subscribing to PayPal's status page, specifically the Product and API sections for Braintree services.

Handling exceptionsanchor

Handling exceptions is straightforward and follows common language conventions.

  1. Ruby
begin
  customer = gateway.customer.find("an_unknown_customer_id")
rescue Braintree::NotFoundError => e
  puts e.message
end

Our list of available exceptions is up-to-date with the latest versions of the server SDKs. Check our migration guide if you are integrating from an older version.

Authentication Erroranchor

Braintree::AuthenticationError

Raised when your API keys are incorrect. If you're getting this exception when first integrating, double-check that you haven't accidentally tried to use your sandbox keys in production or vice-versa.

Authorization Erroranchor

Braintree::AuthorizationError

Raised when the API key that you're using is not authorized to perform the attempted action according to the role assigned to the user who owns the API key.

This error can also occur if the data you submitted was malformed – either a parameter isn't in the allowed list, or it is at the wrong location in the nested parameters.

Configuration Erroranchor

Braintree::ConfigurationError

Raised when the gem isn't configured. Make sure you have environment, merchant_id, public_key, and private_key.

  1. Ruby
gateway = Braintree::Gateway.new(
  :environment => :sandbox,
  :merchant_id => "your_merchant_id",
  :public_key => "your_public_key",
  :private_key => "your_private_key",
)

Invalid Challengeanchor

Braintree::InvalidChallenge

Raised when the webhook challenge you attempt to verify is in an invalid format.

Invalid Signatureanchor

Braintree::InvalidSignature

Raised when the webhook notification you attempt to parse has an invalid signature.

This could be caused by a payload being modified in transit or if you attempt to parse messages that did not originate from our servers.

Not Found Erroranchor

Braintree::NotFoundError

Raised when the record that you're trying to operate on can't 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.

Server Erroranchor

Braintree::ServerError

Raised when something goes wrong on the Braintree server when trying to process your request.

SSL Certificateanchor

Braintree::SSLCertificateError

Raised when the client library can't verify the server's TLS/SSL certificate. This may indicate an attempted man-in-the-middle attack.

Unexpected Erroranchor

Braintree::UnexpectedError

Raised when an error occurs that the client library is not built to handle. If this happens, there's probably a bug in the client library.

Too Many Requests Erroranchor

Braintree::TooManyRequestsError

Raised when requests associated with your account reach unsafe levels. We may limit API resources by merchant if activity risks negative impact to other merchants.

Upgrade Required Erroranchor

Braintree::UpgradeRequiredError

Raised when you're trying to use a version of the library that is no longer supported. Please see our Server SDK Deprecation Policy for more information.

Validation Faileanchor

Braintree::ValidationsFailed

Raised from bang methods when validations fail.

Timeoutsanchor

Timeout Exceptionanchor

Net::ReadTimeout

Raised when a request times out because it takes longer than the custom timeout limit you set in the server SDKs. A request that returns this exception could still be successful if it processes within the Braintree gateway timeout limit of 60 seconds. Learn more about timeouts.

Gateway Timeout Erroranchor

Braintree::GatewayTimeoutError

Raised when Braintree servers time out delivering a response. For search API calls, this usually indicates the amount of information you are requesting is greater than the amount of time Braintree servers have to retrieve it and send a response. Try breaking down your search calls into smaller batches.

Request Timeout Erroranchor

Braintree::RequestTimeoutError

Raised when Braintree servers time out waiting for the entire request from your server. This usually indicates an issue upstream of Braintree.

Service Unavailable Erroranchor

Braintree::ServiceUnavailableError

Raised when Braintree or a downstream service is unavailable.