Troubleshoot Common Square API Problems

Find solutions to problems common across Square APIs and SDKs. For troubleshooting tips, see the product-specific troubleshooting guide.

• In-App Payments SDK

• Square Payment Form

• OAuth API

• Labor API

• Webhooks Troubleshooting

General problems

My call returns an EXPECTED_INTEGER error code

Cause:

The EXPECTED_INTEGER error code means that Square was expecting information as an integer but was sent something else (for example, a string or a float). The most common cause is a Money object with an invalid amount value.

Solution:

• Make sure the amount value is specified in the smallest denomination of the currency used. For example, the smallest currency denomination for USD is cents.

• Make sure the amount value is specified as a positive integer.

• Make sure the amount value is greater than, or equal to, the valid minimum amount. Valid minimums are determined by the Location.country associated with the account:

  • The United States and Canada. amount values must be integers greater than or equal to 1.

  • Australia, Japan, and the United Kingdom. amount values must be integers greater than or equal to 100.

For more information, see Working with Monetary Amounts.

My call returns a RATE_LIMITED error code

Cause:

If your application sends a high number of requests to Square APIs in a short period of time, Square might temporarily stop processing your requests and return RATE_LIMITED errors.

Solution:

Your application should monitor responses for 429 RATE_LIMITED errors and use a retry mechanism with an exponential backoff schedule to resend the requests at an increasingly slower rate. It is also a good practice to use a randomized delay (jitter) in your retry schedule.

Python errors while parsing with ValueError: No JSON object could be decoded

Cause:

Your client library does not chunk decode the JSON response. Square API endpoints return responses in a Transfer-Encoding: chunked format. Many libraries, including our Connect SDKs, handle the decoding automatically for you. However, the Python httplib library and most native JSON libraries return the raw chunked request body.

Solution:

• You should install and develop using the Square SDKs. These SDKs add a helper wrapper that make it easier to integrate with Square APIs.

• If you do not use these SDKs, you can verify chunk encoding by checking the response for the Transfer-Encoding header. Alternatively, you can examine the response body. If it alternates lines of hexadecimal numbers and JSON text, the response is chunked. Learn more about chunked transfer encoding.

My resource update call returns an VERSION_MISMATCH error code

A 400 Bad Request response is returned when an update is attempted with a stale resource.

{
  "errors": [
    {
      "code": "VERSION_MISMATCH",
      "detail": "The version of the resource on the server does not match the version provided with the request. Please re-fetch the resource and try again.",
      "field": "version",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}

Cause:

After the local client endpoint got the resource to update, another client endpoint wrote an update to this resource, which incremented the resource version and made the local resource version stale.

Solution:

Get the current version of the resource, update it, and try the update operation again.

My call to to the Sandbox returns a GONE error code

Cause:

The GONE error code means that you have made a call on the Square Legacy Sandbox which is no longer supported.

Solution:

• Get new Square Sandbox credentials for your application in the Developer Dashboard.

• Update the Square domain of the API URL configured in your SDK client to squareupsandbox.com.

• Configure your SDK client to use the sandbox credentials

For information about testing with the Square Sandbox, see Test in the Sandbox.

Authentication problems

My API call returns an AUTHENTICATION_ERROR error code

Cause:

Authorization errors are typically caused by typos or mismatched credentials.

Solution:

• Make sure you have replaced placeholders and default values in the sample code with valid application credentials.

• Make sure you have configured your credentials correctly. For example, if you are testing calls in production, make sure you are not using Sandbox credentials.

• Make sure you are using the right credential type. For example, application IDs are used for OAuth API calls but access tokens are used in Payments API calls.

• If you are using SqPaymentForm to generate a credit card nonce, make sure the credentials you use in your sqpaymentform.js file match the credentials you use for API calls that use that nonce.

• For REST calls, make sure you have set the Authorization header key to "Bearer" and a valid access token.

For more information about writing correct authentication code, see Best Practices.