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.
{
"error": {
"statusCode": 404,
"code": "order_not_found",
"message": "Order not found"
}
}| Field | Meaning |
|---|---|
error.statusCode | The HTTP status code, repeated in the response body. |
error.code | A stable machine-readable code. Present for known application failures. |
error.message | What went wrong, written for a human. |
error.details | Structured 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.
{
"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:
{
"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
| Code | Means | What to do |
|---|---|---|
400 | The request is malformed, fails validation, or asks for something that cannot be ordered. | Fix the request. Retrying it unchanged will fail again. |
401 | The 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. |
404 | No such route, or no such resource in this store. | Check the path and resource ID. Resources from another store also return 404. |
409 | An order already exists with this customStoreOrder.externalOrderId. | Fetch the existing order instead of creating another. |
415 | An uploaded artwork uses an unsupported file format. | Provide a PNG or JPEG file. |
429 | You have gone past the rate limit. | Wait for the Retry-After header, then retry. See Rate limits. |
500 | Something 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:
{
"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.