Troubleshooting common Clover REST API error codes

Getting started building a web app with the Clover REST API is quick and easy. As you explore all the API’s endpoints, you may run into unsuccessful API requests. As a developer advocate, I see a wide variety of issues that can be quickly remedied. If you’re running into issues, try these common solutions. This isn’t meant to be an exhaustive list of every issue you could run into. However, when new issues and solutions arise, I’ll add them to this list.

400 Bad Request

Check your query and body parameters
Make sure you are passing in required parameters. For example, if you try to create add a line item without a cost to an order, you’ll receive this error.

"name": "Custom line item",
"price": 100
//Need to set price or you'll get a 400 error

400 Internal Error

Narrow down your query using filters like modifiedTime

If you are performing an intensive query (e.g., filtering on an unindexed field–which you generally shouldn’t do), the server might not return a result. If you are able to narrow down your query to a more specific timeframe using modifiedTime or createdTime, this will decrease the likelihood of running into this error.


Read more about other filters you can perform in the Developer Docs.

401 Not Authorized

Make sure to include your API token
In order to use the REST API, you’ll need an API token that shows you’ve been authorized access to a merchant’s data. You should include the token in the header of your request:

curl --header "Authorization: Bearer <API_Token>" --header "Content-Type: application/json"{mId}

Don’t have an API token? Read our Developer Docs on how to generate an API token using OAuth.

Make sure your app has the correct permissions.
Your app requires the read/write permissions for the data you’re trying to access. For example, if your app is trying to read order information, your app will need that read permission. You can update your app’s requested permissions in your Developer Dashboard.

Uninstall and reinstall the app after updating permissions.
Apps are only granted the permissions requested at the time of installation. Therefore, if you request additional permissions, merchants will need to uninstall and reinstall your app to grant the new permissions.

Generate a new API token
If a merchant uninstalls and reinstalls your app, any old cached API tokens will be expired. You will need to generate new tokens through OAuth or the Clover Android SDK.

Check your merchant ID and environment
If you use sandbox credentials in our production environment or vice-versa, you will get a 401 Unauthorized error. Any typos in merchant ID or API token will also lead to an error. For example, if you switch up merchants and use the incorrect ID or API token, you’ll end up with an error.

404 Not Found

Check for typos
If you’re getting a 404 Not Found, you might have a typo in your query. If you’re unsure on spelling or formatting check out our Developer Docs and API Reference. There also might be more information in the details of the response.

429 Too Many Requests

Adhere to the rate limits
If you are making API requests successively and are not adhering to our rate limits, you will be returned a 429 Too Many Requests error. Check out my blog post on how to avoid getting rate limited.

If the solutions above don’t resolve your issue, feel free to ask for assistance in the Clover Developer Community or check out our Developer Docs.