Handling Errors
Improve your user experience by handling error information from Square APIs and SDKs.
On this page
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 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.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.
Note
A 5xx
status code indicates that the error occurred on the server side and therefore cannot be corrected by the client. If you receive a 5xx
error, contact Developer Support, join our Slack, or reach out to your Square Account Manager.