Build Basics

Handling Errors

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

Connect v2 errors
Permalink Get a link to this section

All Connect v2 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 Connect v2 Error type for more information.

Connect v1 errors
Permalink Get a link to this section

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
Permalink Get a link to this section

Connect v2 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)
Permalink Get a link to this section

  • 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)
Permalink Get a link to this section

  • 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)
Permalink Get a link to this section

  • 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)
Permalink Get a link to this section

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

Not Acceptable (406)
Permalink Get a link to this section

  • not_accecptable — 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 406 status.

Unprocessable Entity (422)
Permalink Get a link to this section

  • 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)
Permalink Get a link to this section

  • 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)
Permalink Get a link to this section

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

Service Unavailable (503)
Permalink Get a link to this section

  • service_unavailable — The Connect API service is currently unavailable.