Troubleshoot the Payments API

Applies to: Payments API

Learn about the error codes returned by the Payments API.

Link to section


If an error occurs when attempting to create a payment, the CreatePayment endpoint returns a list of error objects describing the issues encountered. Each error object includes the following elements:

  • code identifies the error type. For a list of CreatePayment error codes, see Error descriptions.
  • detail elaborates on what caused the error and includes the error type.
  • category identifies the error category.

The following is an example error:

"errors": [ { "code": "INSUFFICIENT_FUNDS", "detail": "Authorization error: 'INSUFFICIENT_FUNDS'", "category": "PAYMENT_METHOD_ERROR" } ]

The errors array can return multiple errors.


A comprehensive list of error codes is available in the technical reference (see ErrorCode). The endpoint-specific errors are documented in the endpoint technical reference. For example, see CreatePayment and RefundPayment. The following sections provide additional information about specific errors.

Link to section

CreatePayment errors (additional information)

This section provides additional details about specific errors that the CreatePayment endpoint returns.

Error code GIFT_CARD_AVAILABLE_AMOUNT - When using a Square gift card as a payment source in a CreatePayment request, you can allow taking a partial payment by adding the accept_partial_authorization parameter in the request. If the gift card doesn't have a sufficient balance to pay the entire amount_money specified in the request, the request succeeds. For more information, see Partial Payment Authorizations.

However, taking a partial payment doesn't work if your request also includes tip_money, app_fee_money, or both. Square declines such payments and returns the following error:

  • The error details provide the amount available on the gift card at the time of the request. The amount is a string representation in the smallest denomination of the applicable currency. For example, in USD the amount is specified in cents.
  • The error code appears in an array along with the INSUFFICIENT_FUNDS error.

The following is an example set of errors:

{ "errors": [ { "code": "INSUFFICIENT_FUNDS", "detail": "Gift card does not have sufficient balance for requested amount and tip.", "category": "PAYMENT_METHOD_ERROR" }, { "code": "GIFT_CARD_AVAILABLE_AMOUNT", "detail": "4494", "category": "PAYMENT_METHOD_ERROR" } ] }

In addition to the errors, the example shows the gift card balance of $44.94 USD. You can review this amount and submit a new CreatePayment request (with tip_money and amount_money) that fits within the available balance.

Link to section

See also