Handling Errors

Learn about error responses and best practices for error handling and logging.

Square APIs always return a response. If a request succeeds, the response includes a header with an HTTP status code of 200. If a request fails, the response includes a header with a status code ranging from 400 to 599.

Error responses include an errors array with an Error object for each error that occurred while processing the request. If multiple errors are returned, the status code matches the first one. Depending on how the request is processed, it's possible to receive a subsequent error response after fixing and retrying a request.

Bulk endpoints are an exception; they might also return errors for individual operations within a 200 response.

The Error object provides error information using the following properties:

• category - A high-level classification of the error. For a complete list of category values, see ErrorCategory.
• code - A specific identifier for the error. For a complete list of error codes, see ErrorCode.
• detail - A human-readable error description for developers, not intended to be customer facing. This is an optional error field.
• field - The name of the field in the original request (if applicable) that the error pertains to. This is an optional error field.

The following example requests return an error response:

• GetPayment using a nonexistent payment ID

  Request

  Error response

  Get payment

  cURL

• UpdateCustomer using invalid values

  Request

  Error response

  Update customer

  cURL

Avoid presenting a raw Error object directly to the user. Instead, your code should anticipate common errors and respond with user-friendly messages. The overall tone of these messages should be similar to other messages that your application shows to users. Direct users to contact your own support team (instead of Square support) about any questions or issues that arise when using your application.

Your application should respond gracefully to errors. Some common techniques include the following:

• Catch and handle errors so that the application doesn't crash or freeze. Use try-catch blocks or similar mechanisms to handle exceptions and determine next steps.

• If an API call fails, consider providing a fallback option or alternative approach. This can help users perform their tasks even if an API is temporarily unavailable.

• Set up a continuous monitoring mechanism for the application to collect information about errors and report them. This can help identify recurring issues and allow developers to proactively address them.

• Write errors to an error log so developers can diagnose and fix issues. This can include logging relevant information such as error type, stack trace, user context, and any other useful details.

  Did you know?

  Square provides an API Logs feature that captures data about your API calls. You can use the log data for diagnostics, troubleshooting, and auditing.

The Square SDKs provide language-specific error-handling mechanisms that you can use in your code. For more information and code snippets, see the following:

• Using the Square Java SDK
• Using the Square .NET SDK
• Using the Square Node.js SDK
• Using the Square PHP SDK
• Using the Square Python SDK
• Using the Square Ruby SDK

If you receive an AUTHENTICATION_ERROR error with a 401 Unauthorized status, the access token used in the API request is probably invalid.

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

During development, these UNAUTHORIZED errors are commonly encountered when switching between the production and Sandbox environments. To troubleshoot, first make sure you're using the correct access token for the target environment:

1. If needed, find the access token and target environment in the failing request. For more information, see Use an access token in your code.
2. Use the access token to call RetrieveTokenStatus in the production or Sandbox environment. A valid token returns a 200 OK response and a scopes array that lists the authorized permissions.

Other issues might result in AUTHENTICATION_ERROR errors. For example:

• The provided access token is expired or revoked, or you're sending the encrypted value.
• The provided access token doesn't grant sufficient permissions to use the API endpoint you're calling.
• The Authentication header isn't properly formatted with a bearer token or the access token is missing from the request.
• The application ID and secret you provided in the ObtainToken request is from the wrong (production or Sandbox) environment.
• You didn't remove { }, < >, or other placeholder characters that you copied from a code example.

Make sure to handle these issues in your implementation. For example, test with specific OAuth permissions, regularly refresh access tokens, and listen for oauth.authorization.revoked events. For more information, see OAuth Best Practices and Move OAuth from the Sandbox to Production.

Errors in the AUTHENTICATION_ERROR category return a 401 or 403 status code with one of the error codes shown in the following table:

If your application sends a high number of requests to Square APIs in a short period of time, Square might temporarily stop processing your requests and return RATE_LIMITED errors. These errors have a 429 Too Many Requests status.

Your application should monitor responses for these errors and use a retry mechanism with an exponential backoff schedule to resend the requests at an increasingly slower rate. It's also a good practice to use a randomized delay (jitter) in your retry schedule to avoid a thundering herd effect.

• TLS and HTTPS