Status code and error reference

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.

200The requested action was successfully processed by the device
209The operation was canceled by user request
400The request is invalid, and subsequent calls will continue to fail; do not repeat the call.
401An invalid bearer token has been provided. The call may be repeated if the provided bearer token is updated.
415The request is invalid and contains request data in an unsupported format. This call may be repeated if the content is changed to a supported format.
500The request processing failed with an unknown error, and the processing state of the operation is indeterminate. Do not repeat the call without additional analysis.
501The device is not available for this call and cannot respond; do not repeat the call
503The device is not available because it is handling another request. The current request can be repeated at a later time.
504The device did not respond in a timely manner. This request can be repeated at a later time.

Error messages



A 200 response does not necessarily mean that the transaction (a charge or refund, for example) was successful. It only indicates that the request was received and processed successfully by the specified Clover device.

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 was sent, and then the POS attempted to return to the welcome screen by calling /device/v1/welcome. The charge request started the payment flow, and this flow blocks other calls until the customer has completed their payment or the request times out. You can see the first request (CreateCharge) in the error message.

Device connection issues

While a transaction is being processed, situations can arise that can interrupt the connection between the POS and the device. 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. Because of this, error messages may be returned from any of those intermediate services if a failure occurs.

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

  "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 stating that the request is unauthorized:

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

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

Did this page help you?