Handling Errors

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."
    }
  ]
}

See the Square Error type for more information.

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 may 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 both use HTTP protocol status codes to indicate errors. Error code values range from 400 to 599. Currently supported HTTP status codes are documented below along with the associated Connect v1 error type strings.

Applications should be ready to handle any of the following errors.

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 was revoked, expired, or 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.

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.