Improve your user experience by handling error information from Square APIs and SDKs.
Build Basics

Handling Errors

Square APIs always return a response. If an endpoint request fails, the response body includes an errors array as explained in the following section.

Link to section
Square API errors

When a request fails, Square endpoints return a response that includes the errors field in the body. It provides one or more errors of the Error type. The following is an example response of a failed CreatePayment request:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
{
  "errors": [
    {
      "category": "AUTHENTICATION_ERROR",
      "code": "VALUE_EMPTY",
      "detail": "Field must not be blank.",
      "Field" : "idempotency_key"
    }
  ]
}

Note

The Square Connect V1 API is a deprecated API. If you are still using the API, note that all Connect V1 endpoints return JSON error responses to indicate the related HTTP protocol status code and a human-readable message describing the error. The error message is always in English. For example:

  • 1
  • 2
  • 3
  • 4
{
  "type": "not_found",
  "message": "The resource specified in the request wasn't found.",
}

Link to section
Protocol status codes

Square API endpoints use HTTP protocol status codes to indicate errors. For more information about HTTP response status codes, see HTTP response status codes. The error code values range from 400 to 599.

Link to section
Additional build basics considerations

There are several other introductory topics provided for a new developer to quickly learn the basics of developing applications with Square. For more information, see Basics of Building Applications with Square.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

On this page