API Response Codes

Response status codes

EasyStore uses conventional HTTP response codes to show whether an API request worked. Codes in the 2xx range mean success, 4xx codes mean the request couldn't be completed with the information given (for example a missing or invalid parameter), and 5xx codes mean something went wrong on EasyStore's side (these are rare).

Error format

Errors are returned as JSON with a human-readable message and a machine-readable code. Use code in your error handling; the message wording can change.

{
  "error": {
    "type": "Forbidden",
    "message": "Permission denied.",
    "code": "permission_denied"
  }
}

Status codes

Code	Meaning	What to do
200 OK	The request worked.
400 Bad Request	The request was invalid, often because a required parameter is missing or a value is wrong.	Check `error.message`, fix the request and retry.
401 Unauthorized	The `EasyStore-Access-Token` header is missing.	Send the access token with every request.
402 Payment Required	The store's EasyStore subscription has expired.	Pause calls for this store and try again later.
403 Forbidden	`permission_denied`: the access token is invalid, the app was uninstalled or disabled in the store, or your app doesn't have the scope this endpoint needs.	If it fails for every endpoint, treat the app as uninstalled or disabled for that store. If only some endpoints fail, request the missing scope.
404 Not Found	The endpoint or store doesn't exist.	Check the URL and the `shop` domain.
408 Request Timeout	The request timed out (`request_timeout`). Some endpoints also return 408 with `record_not_found` when the record (for example an order ID) doesn't exist.	Check `error.code`: retry a timeout with backoff; don't retry `record_not_found`.
422 Unprocessable Entity	The request was well-formed but couldn't be processed, for example because of a validation rule.	Check `error.message` and fix the data.
429 Too Many Requests	You hit the API call limit.	Slow down and retry with exponential backoff.
500 Server error	Something went wrong on EasyStore's end (`something_went_wrong`).	Retry later with backoff.

App-specific errors such as redeem_timeout are listed in App Development: Error messages.