Status codes and errors reference

United States

Status codes

The API returns messages in one of two categories—Successful (2xx) or Unsuccessful (4xx and 5xx). The following table describes the status codes that may be returned in response to a request.

200Requested action successfully processed by the device.
209Operation canceled by user request.
400Request is invalid, and subsequent calls will continue to fail. Do not repeat the call.
401Invalid bearer token provided. You can repeat the call if the provided bearer token is updated.
415Request is invalid and contains request data in an unsupported format. You can repeat the call if the content is changed to a supported format.
500Request processing failed with an unknown error, and the processing state of the operation is indeterminate. Do not repeat the call without additional analysis.
501Device is not available for this call and cannot respond. Do not repeat the call.
503Device is not available because it is handling another request. You can repeat the current request later.
504Device did not respond in a timely manner. You can repeat the current request later.

Error messages



A 200 response does not necessarily indicate that the transaction, example: a charge or refund, is successful. It only indicates that the specified Clover device received and processed the request successfully.

Conflicting requests

If the POS makes a request while the Clover device is still processing a previous request, an error message is returned.

  "message": "Conflicting request (CreateCharge) currently in progress for operation type: FOREGROUND",

In this example, a charge request is sent, and then the POS attempts to return to the welcome screen by calling /device/v1/welcome. The charge request starts the payment flow, and this flow blocks other calls until the customer completes the payment, or the request times out. You can view the first request of CreateCharge in the error message.

Device connection issues

During transaction processing, the connection between the POS and the device may be interrupted. See Handling communication issues for more information.

Cloud connection errors

The Cloud Pay Display app depends on several intermediate network requests before it receives and processes a request from a POS app. If a failure occurs, any of those intermediate services may return an error message.

If Cloud Pay Display is not running when the POS makes a request, an error message is returned that the device is unreachable:

  "message": "An error has occurred and we could not establish a connection to your Clover device: C030UQ50550081 within the timeout period of 15 second(s). Please manually start Cloud Pay Display on your Clover device and try again.",
  "type": "ERROR"

Auth token issues

If you send a request with an invalid or missing auth token, an error message is returned that the request is unauthorized:

  "message": "Unauthorized",
  "type": "ERROR"

Verify that your auth token is valid and present, and then resend the request.