Handling Errors

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

Square API errors

All Square API endpoints include an errors array in their response body when the request fails. For example:

{
  "errors": [
    {
      "category": "AUTHENTICATION_ERROR",
      "code": "UNAUTHORIZED",
      "detail": "This request could not be authorized."
    }
  ]
}

For more information, see Square Error.

Connect v1 errors

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 and might change over time. For example:

{
  "type": "not_found",
  "message": "The resource specified in the request wasn't found.",
}

HTTP protocol status codes

Square and Connect v1 endpoints use HTTP protocol status codes to indicate errors. Error code values range from 400 to 599. Currently supported HTTP status codes are documented in the following sections, along with the associated Connect v1 error type strings.

Applications should be ready to handle any of the errors that can be returned by Square. For a complete list of error codes, see ErrorCode in the Square API technical reference.

The following error codes are the most frequently returned:

Bad Request (400)

• bad_request.missing_parameter. A required parameter was missing from the request.

• bad_request.invalid_parameter. The request included an invalid parameter.

• bad_request. The request was otherwise malformed.

Unauthorized (401)

• service.not_authorized. The application is not authorized to make the request.

• oauth.revoked. The application access token was revoked.

• oauth.expired. The application access token has expired.

Forbidden (403)

• forbidden. The requesting application does not have permission to access the resource, typically because the OAuth token has insufficient permission scope.

Not Found (404)

• not_found. The resource specified in the request was not found.

Not Acceptable (406)

• not_acceptable. The endpoint is unable to fulfill the client request in a way that satisfies the structural guidelines included in the request headers. For example, requesting a binary response from a JSON endpoint.

  Important

  Only Connect v2 endpoints return a 406 status error.

Unprocessable Entity (422)

• unprocessable_entity. The request is well formed but has semantic errors. For example, the application attempted to create an item variation with the same SKU as an existing variation.

Too Many Requests (429)

• too_many_requests. The Connect API has received too many requests associated with the same access token or application ID in too short a time span. Try the request again later.

Internal Server Error (500)

• internal_server_error. Square encountered an unexpected error processing the request.

Service Unavailable (503)

• service_unavailable. The Connect API service is currently unavailable.