Pengine Store API
Guides

Errors

What a failure looks like, and which calls are safe to retry.

Failures from a Store API endpoint return an error envelope. Known failures include a stable code for programmatic handling and may include structured details.

404 Not Found
{
  "error": {
    "statusCode": 404,
    "code": "order_not_found",
    "message": "Order not found"
  }
}
FieldMeaning
error.statusCodeThe HTTP status code, repeated in the response body.
error.codeA stable machine-readable code. Present for known application failures.
error.messageWhat went wrong, written for a human.
error.detailsStructured information about the affected fields or line items, when available.

Branch on the code, not the message

Message text is not part of the API contract and can change without a new version. Use error.code for a specific known failure and error.statusCode for broader handling.

Validation failures

When a request body or query string does not validate, the response uses validation_failed. Each entry in details names a field path and lists every rule that field failed.

400 Bad Request
{
  "error": {
    "statusCode": 400,
    "code": "validation_failed",
    "message": "The request is invalid",
    "details": [
      {
        "path": "lineItems[0].quantity",
        "messages": ["lineItems.0.quantity must not be less than 1"]
      },
      {
        "path": "shippingAddress.lastName",
        "messages": ["shippingAddress.lastName should not be empty"]
      }
    ]
  }
}

Query parameters are validated the same way:

400 Bad Request
{
  "error": {
    "statusCode": 400,
    "code": "validation_failed",
    "message": "The request is invalid",
    "details": [
      {
        "path": "limit",
        "messages": ["limit must not be greater than 100"]
      }
    ]
  }
}

Unrecognized fields and query parameters fail validation. Each one appears in details with the message property <name> should not exist. Send only the fields and parameters documented for the endpoint.

Status codes

CodeMeansWhat to do
400The request is malformed, fails validation, or asks for something that cannot be ordered.Fix the request. Retrying it unchanged will fail again.
401The key is missing or wrong for this store, the store is inactive, or the API is disabled.Check the key and store ID. Do not retry automatically.
404No such route, or no such resource in this store.Check the path and resource ID. Resources from another store also return 404.
409An order already exists with this customStoreOrder.externalOrderId.Fetch the existing order instead of creating another.
415An uploaded artwork uses an unsupported file format.Provide a PNG or JPEG file.
429You have gone past the rate limit.Wait for the Retry-After header, then retry. See Rate limits.
500Something broke on our side.Retry with backoff. If it persists, contact support with the time and the path.

The API does not return 403. Resources outside the authenticated store return 404.

Requests that never matched a route

A path that is not served, including a version that does not exist, is a plain 404:

404 Not Found
{
  "message": "Cannot GET /store-api/2025-01/stores/ovy3u54frpsl4sd963aja0h1/products",
  "error": "Not Found",
  "statusCode": 404
}

If a whole integration starts returning this, check the version segment in your base URL first.

A request body that is not valid JSON (400) or is larger than 10 MB (413) gets the same plain shape. These requests are rejected before they reach an endpoint.

What is safe to retry

GET requests are safe to retry after a timeout, 429, or 500. Apply exponential backoff and honor the Retry-After header for 429 responses.

An order request that times out may still have succeeded. Send customStoreOrder.externalOrderId with every order to make retries safe:

  • The retry succeeds with 201. The first attempt never landed.
  • The retry fails with 409. The first attempt did land, and the order exists.

After a 409, find the order you already have rather than creating another:

curl "https://api.pengine.io/store-api/2026-08/stores/$STORE_ID/orders?filter[externalOrderId]=web-10482" \
  -H "X-API-Key: $PENGINE_API_KEY"

Without an external order ID there is no protection

Without customStoreOrder.externalOrderId, each request creates a distinct order. A retry after a timeout can create and bill the same order twice. Always use your own order number as the external ID.

On this page