Errors

Error format

The Mage Loyalty API uses conventional HTTP status codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, codes in the 4xx range indicate a client error, and codes in the 5xx range indicate a server-side problem. All errors return a JSON body following the JSON:API error format:

{
  "errors": [
    {
      "status": "422",
      "title": "Insufficient Points",
      "detail": "Customer has 200 points but this reward costs 500"
    }
  ]
}

Error response codes

Status	Meaning
`400`	Bad Request — Missing or invalid fields in the request body
`401`	Unauthorized — Missing, invalid, or revoked API key
`403`	Forbidden — Read-only API key attempted a write operation, customer is excluded from the loyalty program, or customer is not on the required VIP tier
`404`	Not Found — The requested resource does not exist for this shop
`405`	Method Not Allowed — The HTTP method is not supported on this endpoint
`409`	Conflict — Duplicate action, e.g. awarding an earning rule already completed by this customer
`422`	Unprocessable Entity — The request is well-formed but cannot be completed, e.g. insufficient points
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error — Something went wrong on our end
`503`	Service Unavailable — Unable to connect to Shopify

The status field is always returned as a string (for example "404"), not a number.

Example error bodies

A request for a customer that does not exist returns 404 Not Found:

{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "Customer '6789012345' not found"
    }
  ]
}

A request body that is not valid JSON returns 400 Bad Request:

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Invalid JSON body"
    }
  ]
}

REST API

API Resources

Webhook Events

Shopify Metafields

Error format

Error response codes

Example error bodies

​Error format

​Error response codes

​Example error bodies

Error format

Error response codes

Example error bodies