Troubleshooting Common API problems

Look up solutions to common problems.

PHP (Connect SDK)
Connect SDK
Command Line

On This Page

General problems

My call returns an EXPECTED_INTEGER error code.


The EXPECTED_INTEGER error code means 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.


  • Make sure the amount value is specified in in the smallest denomination of the currency used. For example, the smallest currency denomination for USD is pennies.
  • Make sure the amount value is specified as a positive integer number.
  • 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:
    • United States and Canadaamount values must be integers greater than, or equal to, 1.
    • Australia, Japan, and the United Kingdomamount values must be integers greater than, or equal to, 100.

Read more about working with monetary amounts.

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


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, will handle this automatically for you. However, Python's httplib and JSON libraries will return the raw chunked request body.


  • We strongly recommend you install and develop using our Connect SDKs. These SDKs add a helper wrapper that make it easier to integrate with Connect APIs.
  • If you do not use our SDKs, you can verify chunk encoding by checking the response for the Transfer-Encoding header. Alternatively, you can also examine the response body. If it alternates lines of hexadecimal numbers and JSON text, then the response is chunked. Learn more about 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"


After the local client endpoint got the resource to update, another client endpoint has written an update to this resource which incremented the resource version, making the local resource version stale.


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

Authentication problems

My API call returns an AUTHENTICATION_ERROR error code.


Authorization errors are typically caused by typos or mismatched credentials.


  • Make sure you have replaced placeholders and default values in 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 Personal Access Tokens are used in Transaction 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.

Note: Older APIs sometimes refer to the application ID as a client ID (client_id) .

Transactions API problems

I get a not_found error when calling the Charge endpoint.


Receiving a not_found error from the Charge endpoint is most commonly caused by one of the following issues:

  • Not using the payments form to obtain a card nonce before calling the Charge endpoint.
  • Calling the Charge endpoint without providing a card nonce in the request.
  • Attempting to charge a card nonce with credentials different from those used to generate the card nonce. For example, attempting to use a live OAuth access token to charge a card_nonce generated with sandbox credentials will result in a not_found error.


  • Use only the Square payment form to generate card nonces. See the Payment form Setup Guide for more information.
  • Be sure to charge a card_nonce with the same credentials used to generate it. You can find your application credentials in the Application Dashboard.

Webhooks problems

I did not receive my webhook notification


Square Webhook notifications typically send within 60 seconds of the associated event. Applications must acknowledge the notification by responding within 10 seconds with an HTTP 2xx response code to acknowledge successful delivery. Unsuccessful deliveries are retried for up to 72 but after 72 hours have elapsed, the notification is discarded and will not be sent again.


Verify your application is responding to notification deliveries in the required time window with an HTTP 2xx response code. For more information, see the Webhooks guide.

Square Payment Form problems

The SqPaymentForm iFrame is not loading


The hosting site does not have HTTPS enabled or the page is rendering with the payment form in a hidden div.


  • Secure your site with TLS to enable HTTPS calls or serve your website on localhost to test. See the HTTPS Overview for help getting HTTPS enabled for your site.
  • If you use the payment form in a hidden div, call SqPaymentForm.recalculateSize() when exposing the div to force SqPaymentForm to re-render the iframes.

SqPaymentForm will not generate form fields on a standard, multi-page web application


By default, SqPaymentForm automatically generates form fields when it detects a DOMContentLoaded event (when the hosting page finishes loading) and it is properly initialized with a valid application ID and location ID. A failure to load properly typically means 1 of the following is likely true:

  • The application ID, location ID, or both were not provided.
  • The application ID and location ID combination is invalid. For example, the one of the IDs is a sandbox ID and one is a production ID.
  • The application ID is incorrectly set with an access token (e.g., your Sandbox Access Token or Personal Access Token). These values are not the same as the application ID.


Check your initialization information and verify the values provided are correct:

 1// Set the application ID
 2var applicationId = "REPLACE_ME";
 4// Set the location ID
 5var locationId = "REPLACE_ME";
 7// Create and initialize a payment form object
 8var paymentForm = new SqPaymentForm({
 9  ...

SqPaymentForm will not generate form fields on a single-page web application


By default, SqPaymentForm automatically generates form fields when it detects a DOMContentLoaded event (when the hosting page finishes loading) and it is properly initialized with a valid application ID and location ID. The DOMContentLoaded event may not be triggered in single-page web applications when the form is initialized after the DOMContentLoaded event has fired.


To manage the payment form initialization manually, set the autoBuild configuration option to false, and add the following function call to the page where you want to initialize the payment form:


Calling paymentForm.build() when SqPaymentForm has already rendered the iframe fields will log an error to the JavaScript console.

SqPaymentForm listeners persisting on a single-page web application


The SqPaymentForm object registers multiple event listeners on your webpage. These listeners go away when control is passed to a new page, but if you have a single-page web application, those listeners might remain longer than you want.


To manually remove the listeners from your webpage, add the following function call where you want to clean up after the payment form:


In-App Payments SDK problems

ProGuard causes Android app crashes with fatal exception on getting nonce

Cause: When you build your app with the release profile and enable ProGuard minify, ProGuard strips some classes that the In-App Payments SDK depends on. On first access to these classes at runtime, a NullPointerException is thrown because the required classes have been stripped out of the .apk file.


If you are building your project for released and you have enabled ProGuard minify, update your Android Studio solution Proguard-rules.pro file with the following rules:

1-keep class sqip.** { *; }

Labor API problems

Find problems and solutions related to opening, adding breaks, and closing shifts using the Labor API.

I cannot create a new open Shift for an employee

Square's error response says that the new Shift overlaps other Shifts for an employee who has no other shifts on this day.


The employee has an open shift from a previous day that needs to be closed.


Find the previous shift and verify that the end_at field is null or missing. Close the shift by setting an end_at value value and sending an UpdateShift request for the shift to be closed.

curl https://connect.squareup.com/v2/labor/shifts/search \
 -H 'Content-Type: application/json'                       \
 -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'     \
 -d '{
        "query": {
                "filter": {
                        "status": "OPEN", 
                        "employee_id": ["AN_EMPLOYEE_ID"]

The response to the shift search request is an empty object if the employee does not have an OPEN shift.


When checking for an open shift, use code like the following example and provide the ID of the employee associated with the open shift.

   $shiftQuery = new SquareConnect\model\ShiftQuery();
   $shiftFilter = new SquareConnect\model\ShiftFilter();
   $searchShiftsRequest = new SquareConnect\model\SearchShiftsRequest();
   $employees = Array("EMPLOYEE_ID");
   $searchShiftsResponse = $laborApi->searchShifts($searchShiftsRequest);
   if (method_exists($searchShiftsResponse,'getShifts')) {
      $openShift = $searchShiftsResponse->getShifts()[0];

My createShift call returns the shift I opened in a previous create operation.


A new idempotency key was not generated for this operation.


Generate a new idempotency key and retry the operation.

On closing a shift, the API was unable to service the request

There are no overlapping shifts for the employee and the body of the close request is formed correctly.


The Shift to be closed has an open Break.


Iterate the Break objects in the shift. When a Break with no end_at property is found, set the property to the current time.

My shift query returns too many shifts.


A filter field is invalid (REST only) or an enum value is invalid (REST and SDK). When the search endpoint receives a filter field or enum value it does not recognize, the related filter criteria is ignored.


Enums and JSON field names are case sensitive. Confirm that the field name is correct and lowercase (REST) and the provided enum values match their definition in the Technical Reference.

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow