Handling Errors

Square APIs always return a response. If a request is successful, an HTTP 200 (OK) status is returned with the response. However, if a request fails, the response is accompanied by an Error object with further details. The Error object contains 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 (optional) - A human-readable description of the error.
• field (optional) - The name of the field in the original request (if applicable) that the error pertains to.

The following example shows a GetPayment request for a nonexistent payment ID:

The Error object in the response looks like the following:

{
  "errors": [
    {
      "code": "NOT_FOUND",
      "detail": "Could not find payment with id: 7nDzoTTqoVk6LMeYzfXg2fpcUDaZY",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}

If an error is returned, the response header contains an HTTP status code with a value ranging from 400 to 599. For more information about HTTP response status codes, see HTTP response status codes.

You should 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 that of other messages that your application shows to users.

Your application needs to 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.

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. The underlying HTTP status code is 429 Too Many Requests.

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.

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

• Java
• .NET
• Node.js
• PHP
• Python
• Ruby

• TLS and HTTPS