<- Object

Object

ErrorCode

Indicates the specific error that occurred during a request to a Square API.

Link to section

Values

Link to section

INTERNAL_SERVER_ERROR

A general server error occurred.

Link to section

UNAUTHORIZED

A general authorization error occurred.

Link to section

ACCESS_TOKEN_EXPIRED

The provided access token has expired.

Link to section

ACCESS_TOKEN_REVOKED

The provided access token has been revoked.

Link to section

CLIENT_DISABLED

The provided client has been disabled.

Link to section

FORBIDDEN

A general access error occurred.

Link to section

INSUFFICIENT_SCOPES

The provided access token does not have permission to execute the requested action.

Link to section

APPLICATION_DISABLED

The calling application was disabled.

Link to section

V1_APPLICATION

The calling application was created prior to 2016-03-30 and is not compatible with v2 Square API calls.

Link to section

V1_ACCESS_TOKEN

The calling application is using an access token created prior to 2016-03-30 and is not compatible with v2 Square API calls.

Link to section

CARD_PROCESSING_NOT_ENABLED

The location provided in the API call is not enabled for credit card processing.

Link to section

MERCHANT_SUBSCRIPTION_NOT_FOUND

Beta

A required subscription was not found for the merchant

Link to section

BAD_REQUEST

A general error occurred with the request.

Link to section

MISSING_REQUIRED_PARAMETER

The request is missing a required path, query, or body parameter.

Link to section

INCORRECT_TYPE

The value provided in the request is the wrong type. For example, a string instead of an integer.

Link to section

INVALID_TIME

Formatting for the provided time value is incorrect.

Link to section

INVALID_TIME_RANGE

The time range provided in the request is invalid. For example, the end time is before the start time.

Link to section

INVALID_VALUE

The provided value is invalid. For example, including % in a phone number.

Link to section

INVALID_CURSOR

The pagination cursor included in the request is invalid.

Link to section

UNKNOWN_QUERY_PARAMETER

The query parameters provided is invalid for the requested endpoint.

Link to section

CONFLICTING_PARAMETERS

One or more of the request parameters conflict with each other.

Link to section

EXPECTED_JSON_BODY

The request body is not a JSON object.

Link to section

INVALID_SORT_ORDER

The provided sort order is not a valid key. Currently, sort order must be ASC or DESC.

Link to section

VALUE_REGEX_MISMATCH

The provided value does not match an expected regular expression.

Link to section

VALUE_TOO_SHORT

The provided string value is shorter than the minimum length allowed.

Link to section

VALUE_TOO_LONG

The provided string value is longer than the maximum length allowed.

Link to section

VALUE_TOO_LOW

The provided value is less than the supported minimum.

Link to section

VALUE_TOO_HIGH

The provided value is greater than the supported maximum.

Link to section

VALUE_EMPTY

The provided value has a default (empty) value such as a blank string.

Link to section

ARRAY_LENGTH_TOO_LONG

The provided array has too many elements.

Link to section

ARRAY_LENGTH_TOO_SHORT

The provided array has too few elements.

Link to section

ARRAY_EMPTY

The provided array is empty.

Link to section

EXPECTED_BOOLEAN

The endpoint expected the provided value to be a boolean.

Link to section

EXPECTED_INTEGER

The endpoint expected the provided value to be an integer.

Link to section

EXPECTED_FLOAT

The endpoint expected the provided value to be a float.

Link to section

EXPECTED_STRING

The endpoint expected the provided value to be a string.

Link to section

EXPECTED_OBJECT

The endpoint expected the provided value to be a JSON object.

Link to section

EXPECTED_ARRAY

The endpoint expected the provided value to be an array or list.

Link to section

EXPECTED_MAP

The endpoint expected the provided value to be a map or associative array.

Link to section

EXPECTED_BASE64_ENCODED_BYTE_ARRAY

The endpoint expected the provided value to be an array encoded in base64.

Link to section

INVALID_ARRAY_VALUE

One or more objects in the array does not match the array type.

Link to section

INVALID_ENUM_VALUE

The provided static string is not valid for the field.

Link to section

INVALID_CONTENT_TYPE

Invalid content type header.

Link to section

INVALID_FORM_VALUE

Only relevant for applications created prior to 2016-03-30. Indicates there was an error while parsing form values.

Link to section

CUSTOMER_NOT_FOUND

The provided customer id can't be found in the merchant's customers list.

Link to section

ONE_INSTRUMENT_EXPECTED

A general error occurred.

Link to section

NO_FIELDS_SET

A general error occurred.

Link to section

TOO_MANY_MAP_ENTRIES

Too many entries in the map field.

Link to section

MAP_KEY_LENGTH_TOO_SHORT

The length of one of the provided keys in the map is too short.

Link to section

MAP_KEY_LENGTH_TOO_LONG

The length of one of the provided keys in the map is too long.

Link to section

CUSTOMER_MISSING_NAME

The provided customer does not have a recorded name.

Link to section

CUSTOMER_MISSING_EMAIL

The provided customer does not have a recorded email.

Link to section

INVALID_PAUSE_LENGTH

The subscription cannot be paused longer than the duration of the current phase.

Link to section

INVALID_DATE

The subscription cannot be paused/resumed on the given date.

Link to section

UNSUPPORTED_COUNTRY

The API request references an unsupported country.

Link to section

UNSUPPORTED_CURRENCY

The API request references an unsupported currency.

Link to section

APPLE_TTP_PIN_TOKEN

The payment was declined by the card issuer during an Apple Tap to Pay (TTP) transaction with a request for the card's PIN. This code will be returned alongside CARD_DECLINED_VERIFICATION_REQUIRED as a supplemental error, and will include an issuer-provided token in the details field that is needed to initiate the PIN collection flow on the iOS device.

Link to section

CARD_EXPIRED

The card issuer declined the request because the card is expired.

Link to section

INVALID_EXPIRATION

The expiration date for the payment card is invalid. For example, it indicates a date in the past.

Link to section

INVALID_EXPIRATION_YEAR

The expiration year for the payment card is invalid. For example, it indicates a year in the past or contains invalid characters.

Link to section

INVALID_EXPIRATION_DATE

The expiration date for the payment card is invalid. For example, it contains invalid characters.

Link to section

UNSUPPORTED_CARD_BRAND

The credit card provided is not from a supported issuer.

Link to section

UNSUPPORTED_ENTRY_METHOD

The entry method for the credit card (swipe, dip, tap) is not supported.

Link to section

INVALID_ENCRYPTED_CARD

The encrypted card information is invalid.

Link to section

INVALID_CARD

The credit card cannot be validated based on the provided details.

Link to section

PAYMENT_AMOUNT_MISMATCH

The payment was declined because there was a payment amount mismatch. The money amount Square was expecting does not match the amount provided.

Link to section

GENERIC_DECLINE

Square received a decline without any additional information. If the payment information seems correct, the buyer can contact their issuer to ask for more information.

Link to section

CVV_FAILURE

The card issuer declined the request because the CVV value is invalid.

Link to section

ADDRESS_VERIFICATION_FAILURE

The card issuer declined the request because the postal code is invalid.

Link to section

INVALID_ACCOUNT

The issuer was not able to locate the account on record.

Link to section

CURRENCY_MISMATCH

The currency associated with the payment is not valid for the provided funding source. For example, a gift card funded in USD cannot be used to process payments in GBP.

Link to section

INSUFFICIENT_FUNDS

The funding source has insufficient funds to cover the payment.

Link to section

INSUFFICIENT_PERMISSIONS

The Square account does not have the permissions to accept this payment. For example, Square may limit which merchants are allowed to receive gift card payments.

Link to section

CARDHOLDER_INSUFFICIENT_PERMISSIONS

The card issuer has declined the transaction due to restrictions on where the card can be used. For example, a gift card is limited to a single merchant.

Link to section

INVALID_LOCATION

The Square account cannot take payments in the specified region. A Square account can take payments only from the region where the account was created.

Link to section

TRANSACTION_LIMIT

The card issuer has determined the payment amount is either too high or too low. The API returns the error code mostly for credit cards (for example, the card reached the credit limit). However, sometimes the issuer bank can indicate the error for debit or prepaid cards (for example, card has insufficient funds).

Link to section

VOICE_FAILURE

The card issuer declined the request because the issuer requires voice authorization from the cardholder. The seller should ask the customer to contact the card issuing bank to authorize the payment.

Link to section

PAN_FAILURE

The specified card number is invalid. For example, it is of incorrect length or is incorrectly formatted.

Link to section

EXPIRATION_FAILURE

The card expiration date is either invalid or indicates that the card is expired.

Link to section

CARD_NOT_SUPPORTED

Link to section

INVALID_PIN

The card issuer declined the request because the PIN is invalid.

Link to section

MISSING_PIN

The payment is missing a required PIN.

Link to section

MISSING_ACCOUNT_TYPE

The payment is missing a required ACCOUNT_TYPE parameter.

Link to section

INVALID_POSTAL_CODE

The postal code is incorrectly formatted.

Link to section

INVALID_FEES

The app_fee_money on a payment is too high.

Link to section

MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED

The card must be swiped, tapped, or dipped. Payments attempted by manually entering the card number are declined.

Link to section

PAYMENT_LIMIT_EXCEEDED

Square declined the request because the payment amount exceeded the processing limit for this merchant.

Link to section

GIFT_CARD_AVAILABLE_AMOUNT

When a Gift Card is a payment source, you can allow taking a partial payment by adding the accept_partial_authorization parameter in the request. However, taking such a partial payment does not work if your request also includes tip_money, app_fee_money, or both. Square declines such payments and returns the GIFT_CARD_AVAILABLE_AMOUNT error. For more information, see CreatePayment errors (additional information).

Link to section

ACCOUNT_UNUSABLE

The account provided cannot carry out transactions.

Link to section

BUYER_REFUSED_PAYMENT

Bank account rejected or was not authorized for the payment.

Link to section

DELAYED_TRANSACTION_EXPIRED

The application tried to update a delayed-capture payment that has expired.

Link to section

DELAYED_TRANSACTION_CANCELED

The application tried to cancel a delayed-capture payment that was already cancelled.

Link to section

DELAYED_TRANSACTION_CAPTURED

The application tried to capture a delayed-capture payment that was already captured.

Link to section

DELAYED_TRANSACTION_FAILED

The application tried to update a delayed-capture payment that failed.

Link to section

CARD_TOKEN_EXPIRED

The provided card token (nonce) has expired.

Link to section

CARD_TOKEN_USED

The provided card token (nonce) was already used to process the payment or refund.

Link to section

AMOUNT_TOO_HIGH

The requested payment amount is too high for the provided payment source.

Link to section

UNSUPPORTED_INSTRUMENT_TYPE

The API request references an unsupported instrument type.

Link to section

REFUND_AMOUNT_INVALID

The requested refund amount exceeds the amount available to refund.

Link to section

REFUND_ALREADY_PENDING

The payment already has a pending refund.

Link to section

PAYMENT_NOT_REFUNDABLE

The payment is not refundable. For example, the payment has been disputed and is no longer eligible for refunds.

Link to section

REFUND_DECLINED

Request failed - The card issuer declined the refund.

Link to section

INSUFFICIENT_PERMISSIONS_FOR_REFUND

The Square account does not have the permissions to process this refund.

Link to section

INVALID_CARD_DATA

Generic error - the provided card data is invalid.

Link to section

SOURCE_USED

The provided source id was already used to create a card.

Link to section

SOURCE_EXPIRED

The provided source id has expired.

Link to section

UNSUPPORTED_LOYALTY_REWARD_TIER

The referenced loyalty program reward tier is not supported. This could happen if the reward tier created in a first party application is incompatible with the Loyalty API.

Link to section

LOCATION_MISMATCH

Generic error - the given location does not matching what is expected.

Link to section

IDEMPOTENCY_KEY_REUSED

The provided idempotency key has already been used.

Link to section

UNEXPECTED_VALUE

General error - the value provided was unexpected.

Link to section

SANDBOX_NOT_SUPPORTED

The API request is not supported in sandbox.

Link to section

INVALID_EMAIL_ADDRESS

The provided email address is invalid.

Link to section

INVALID_PHONE_NUMBER

The provided phone number is invalid.

Link to section

CHECKOUT_EXPIRED

The provided checkout URL has expired.

Link to section

BAD_CERTIFICATE

Bad certificate.

Link to section

INVALID_SQUARE_VERSION_FORMAT

The provided Square-Version is incorrectly formatted.

Link to section

API_VERSION_INCOMPATIBLE

The provided Square-Version is incompatible with the requested action.

Link to section

CARD_PRESENCE_REQUIRED

The transaction requires that a card be present.

Link to section

UNSUPPORTED_SOURCE_TYPE

The API request references an unsupported source type.

Link to section

CARD_MISMATCH

The provided card does not match what is expected.

Link to section

PLAID_ERROR

Generic plaid error

Link to section

PLAID_ERROR_ITEM_LOGIN_REQUIRED

Plaid error - ITEM_LOGIN_REQUIRED

Link to section

PLAID_ERROR_RATE_LIMIT

Plaid error - RATE_LIMIT

Link to section

CARD_DECLINED

The card was declined.

Link to section

VERIFY_CVV_FAILURE

The CVV could not be verified.

Link to section

VERIFY_AVS_FAILURE

The AVS could not be verified.

Link to section

CARD_DECLINED_CALL_ISSUER

The payment card was declined with a request for the card holder to call the issuer.

Link to section

CARD_DECLINED_VERIFICATION_REQUIRED

The payment card was declined with a request for additional verification.

Link to section

BAD_EXPIRATION

The card expiration date is either missing or incorrectly formatted.

Link to section

CHIP_INSERTION_REQUIRED

The card issuer requires that the card be read using a chip reader.

Link to section

ALLOWABLE_PIN_TRIES_EXCEEDED

The card has exhausted its available pin entry retries set by the card issuer. Resolving the error typically requires the card holder to contact the card issuer.

Link to section

RESERVATION_DECLINED

The card issuer declined the refund.

Link to section

UNKNOWN_BODY_PARAMETER

The body parameter is not recognized by the requested endpoint.

Link to section

NOT_FOUND

Not Found - a general error occurred.

Link to section

APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND

Square could not find the associated Apple Pay certificate.

Link to section

METHOD_NOT_ALLOWED

Method Not Allowed - a general error occurred.

Link to section

NOT_ACCEPTABLE

Not Acceptable - a general error occurred.

Link to section

REQUEST_TIMEOUT

Request Timeout - a general error occurred.

Link to section

CONFLICT

Conflict - a general error occurred.

Link to section

GONE

The target resource is no longer available and this condition is likely to be permanent.

Link to section

REQUEST_ENTITY_TOO_LARGE

Request Entity Too Large - a general error occurred.

Link to section

UNSUPPORTED_MEDIA_TYPE

Unsupported Media Type - a general error occurred.

Link to section

UNPROCESSABLE_ENTITY

Unprocessable Entity - a general error occurred.

Link to section

RATE_LIMITED

Rate Limited - a general error occurred.

Link to section

NOT_IMPLEMENTED

Not Implemented - a general error occurred.

Link to section

BAD_GATEWAY

Bad Gateway - a general error occurred.

Link to section

SERVICE_UNAVAILABLE

Service Unavailable - a general error occurred.

Link to section

TEMPORARY_ERROR

A temporary internal error occurred. You can safely retry your call using the same idempotency key.

Link to section

GATEWAY_TIMEOUT

Gateway Timeout - a general error occurred.