Premium Apparel API — Error Reference

All errors share a single response shape:

{ "error": "<code>", "message": "...", "details": { } }

details is optional and its shape varies per error (see per-code sections below).

401 invalid_token

The Authorization: Bearer <token> header is missing, malformed, or the token was rejected (expired, revoked, or never valid).

{
  "error": "invalid_token",
  "message": "Bearer token is invalid or expired"
}

Client action: obtain a fresh token and retry the request once. Do not loop — a second 401 after a token refresh indicates a deeper auth problem and should escalate.

403 forbidden

Your token is valid, but this operation is not available to you. This is distinct from 401 (which means the token itself is missing or invalid): a 403 means you are authenticated, but cannot perform this particular action.

{
  "error": "forbidden",
  "message": "You do not have permission to perform that action"
}

Client action: do not retry — the same token will keep being refused. Contact the API provider if you believe you should have access.

404 not_found

The requested resource does not exist on your account. The API does not distinguish between "the resource doesn't exist" and "the resource exists but belongs to another account" — both return this same shape. This prevents reference-space enumeration across accounts.

{
  "error": "not_found",
  "message": "Order not found"
}

Client action: verify the identifier (our_ref for GET /v1/orders/{id}, order_no for GET /v1/orders?order_no=...). Do not retry blindly.

On POST /v1/purchase-orders/lines, this means no purchase order matches the supplied po_no. The message is deliberately generic and identical whether the PO does not exist or simply is not yours — no detail is returned either way, so the reference space cannot be probed.

PUT /v1/products is the exception: an unknown product is NOT a 404. It reports not_found as a per-item result inside a 200, because one unknown product_id must not fail the other 24 products in the batch. A 404 on that endpoint means the route itself was wrong, never that a product was missing:

{
  "product_id": "NEWPROD003",
  "status": "error",
  "error": "not_found",
  "reason": "product_not_found",
  "message": "No product exists with this product_id"
}

Naming the product back is not enumeration here — you supplied the id, so the response confirms nothing you had not already asserted.

On POST /v1/purchase-orders/shipments, the same applies to purchase_line_pk: an unknown line, a line that is not yours, and a line that is not on a purchase order you can see are all one response. It carries no details at all — not even which of your lines was the problem — for the same anti-enumeration reason. Validate the pk against a PO you have read rather than probing.

On PUT /v1/purchase-orders/receipt, an unknown po_no and an unknown purchase_line_pk are the same bare 404, on the same terms. A pk that exists but sits on a different PO is not a 404 - it is a 422 (see below), because you named both and the response confirms nothing new.

409 duplicate_reference

On POST /v1/orders, the supplied order_no already maps to an order on your account. The API is idempotent by order_no — the first successful create wins.

{
  "error": "duplicate_reference",
  "message": "Order with this order_no already exists"
}

Client action: treat the prior create as authoritative. Fetch the existing order via GET /v1/orders?order_no=<the-value> to recover the our_ref that was assigned the first time. Do not retry the create — it will only 409 again.

On the purchase-order endpoints

Three distinct cases, all of which make retrying safe rather than duplicating work:

POST /v1/purchase-orders — the supplied invoice_no is already used by another PO. It is the idempotency key: re-posting the same one never raises a second purchase order, and the message names the PO that already holds it.

{
  "error": "duplicate_reference",
  "message": "Purchase Order P22971 already exists with that invoice_no"
}

POST /v1/purchase-orders/lines — the product is already on that PO. Note this is checked per product, not per SKU: a purchase line holds one product across its size slots, so every size of a product belongs on a single line.

{
  "error": "duplicate_reference",
  "message": "Purchase order P22971 already has a line for product 5000B2AZ - send allow_duplicate_products:true to add another"
}

POST /v1/purchase-orders/shipments — the supplied shipment_ref has already been used. It is the idempotency key, stored on the shipment PO it created: no second purchase order is ever raised for the same ref, and details.po_no names the one that already exists.

{
  "error": "duplicate_reference",
  "message": "Shipment SH-4471 already exists",
  "details": { "po_no": "P23176" }
}

Client action: send every size of a product in one request — they are consolidated onto a single line automatically — rather than one request per size. If you genuinely want a second, separate line for the same product, set allow_duplicate_products: true; be aware this splits that product across two lines, each holding part of the size grid and its own cost. Otherwise treat the 409 as confirmation that a previous attempt already succeeded.

For a shipment, reconcile against the po_no in details and treat the shipment as done. One exception: if your previous attempt on that ref ended in a 502 carrying details.resumable: true, the shipment is only half-written and this 409 is exactly what will keep happening — re-send with resume: true instead. See 502 upstream_error below.

409 conflict

Distinct from duplicate_reference, and the distinction is not cosmetic: duplicate_reference means this reference is taken, and the usual response is to treat a previous attempt as having succeeded. conflict means the request is fine but the record will not accept it in its current state. Retrying an identical payload cannot fix either, but the remediations are unrelated.

Raised by PUT /v1/purchase-orders/lines, POST /v1/purchase-orders/shipments, PUT /v1/purchase-orders/receipt and PUT /v1/orders/{our_ref}/line-items.

On PUT /v1/purchase-orders/lines

Four causes, and the client must not conflate them — one of them is terminal for the whole PO, the other three concern a single product.

{
  "error": "conflict",
  "message": "Purchase order P22971 has been converted to an invoice and no longer accepts line changes"
}

A 422 is not evidence the PO is still open. Converted-to-invoice previously came back as missing_data → 422 and now returns 409. Other non-Order records — stock adjustments and the like — still produce a 422, so the two must be branched on separately.

Under allow_partial: true the three per-product causes do not produce this response at all: the request returns 200 and the affected products appear as action: "failed" rows carrying the underlying code. Only the whole-request cause still surfaces as a 409, in both modes.

On POST /v1/purchase-orders/shipments

Three causes. All are whole-request — a shipment split is never partial — and, unlike the converted-to-invoice case above, none of them is terminal for the PO. Each is correctable.

{
  "error": "conflict",
  "message": "line 319297B1622392262026T: L (ordered 4, asked for 99)",
  "details": { "purchase_line_pk": "319297B1622392262026T" }
}

A converted-to-invoice PO also surfaces here, on the same terms as the table above: terminal, quarantine it.

On PUT /v1/purchase-orders/receipt

Two kinds, and the client must tell them apart. details.reason names the cause and details.retryable says which kind it is. Apart from the one case described under the table, nothing was written.

{
  "error": "conflict",
  "message": "Product ZZTEST is being edited by someone else (FileMaker error 301) - nothing was received, try again shortly",
  "details": { "stage": "lines", "purchase_line_pk": "321054O0843487132026K", "lines_written": 0,
               "reason": "record_locked", "retryable": true }
}

A record_locked can also arrive after some lines have been received, if a record is opened in the moment between checking and writing. details.lines_written says how many; re-sending the identical request finishes the rest, and the lines already done come back changed: false.

On PUT /v1/orders/{our_ref}/line-items

One cause, and it is terminal for that order — the sales-order counterpart of the converted-to-invoice case above, on the same terms.

The order has moved past the point where its value may change: it has been converted from an Order to an Invoice, so the amount is posted and may already sit in the accounting system. The API will not amend it, now or later.

{
  "error": "conflict",
  "message": "Order 0999001 is a Invoice and can no longer accept line changes",
  "details": { "type_desc": "Invoice", "reason": "order_not_amendable" }
}

details.reason names the specific cause and details.type_desc the state the order is actually in, so you can branch without parsing the message. As everywhere on this API, the top-level error is a member of the fixed taxonomy and the open-ended cause rides in details.

Client action: stop syncing that order and alert a human. Do not retry — no future call will succeed, and the correction has to happen as a credit note or adjustment through the normal accounting process, not through this endpoint.

This is deliberately a refusal rather than a partial apply. The whole call is rejected and nothing is written, so an order can never be left in a state neither side predicted. Nothing about the request was wrong; the order simply moved on.

On PATCH /v1/orders/{our_ref}

Two causes, and they are not alike — branch on details.reason.

order_not_amendable — terminal. The order has been converted to an Invoice, so it is posted and the header is no longer the API's to change. Same terms as the line endpoint above.

{
  "error": "conflict",
  "message": "Order 0999001 is a Invoice and can no longer be amended",
  "details": { "type_desc": "Invoice", "reason": "order_not_amendable" }
}

Client action: stop and alert a human. No future call will succeed; the edit has to be made in GW.

conflict — transient. Someone has the order open for editing, so the record is locked and the update was refused rather than half-applied.

{
  "error": "conflict",
  "message": "Order 0999001 is open for editing by someone else (FileMaker error 301) - try again shortly",
  "details": { "reason": "conflict" }
}

Client action: retry the identical payload after a short pause. This one really does clear on its own once the other user moves off the record — and the retry is safe: comments_append ignores text the message already holds, and every other field is a plain set.

Nothing is written in either case. The lock is taken before the first write precisely so that a refusal is never a partial update.

422 validation_error

The request payload, query string, or URL parameters failed JSON-Schema validation. The details object, when present, carries the underlying AJV validation list — useful for pinpointing the first failing field.

{
  "error": "validation_error",
  "message": "body must have required property 'line_items'",
  "details": {
    "validation": [
      { "instancePath": "", "keyword": "required", "params": { "missingProperty": "line_items" } }
    ]
  }
}

Client action: fix the payload; do not retry the same body. Typical causes: missing order_no or line_items, empty line_items array (minItems: 1), integer SKUs, non-integer quantities, unknown top-level fields (additionalProperties: false is strict).

On PUT /v1/orders/{our_ref}/line-items

Line amendment is desired-state: the order ends up holding exactly the lines you send, and a SKU absent from the payload is removed from that order. Three causes are specific to it.

Why moved_to is mandatory on removal. A line removed here is not deleted — it is moved to the order you name, keeping its identity so that any purchase order raised against it follows it instead of being orphaned. Without a destination there is nowhere for it to go, and guessing would silently break the link between the sale and the goods on order. The request is refused instead.

Nothing is written when any of these fire. The whole call is validated before a single change is applied, so a rejected request leaves the order exactly as it was.

On PATCH /v1/orders/{our_ref}

Nothing is written when any of these fire.

On the purchase-order endpoints

A 422 here can come from GWAPI's own schema check or from the upstream system's own validation — the shape is the same, but only the schema-level failures carry details.

Purchase-order specific causes:

Note the SKU format: sku is PRODUCT-SIZE, split on the last hyphen. The product must be active and the size must be one of its 11 size slots — so 5000B2AZ-YM is product 5000B2AZ, size YM. A bad size and an unknown product both surface here.

On POST /v1/purchase-orders/shipments

A validation failure has written nothing. Validation completes for every line before any record is touched, in this layer and upstream, so a 422 never leaves a partly-created shipment behind — there is no PO to clean up and nothing to reconcile.

On a bad size label, read details.valid_sizes. It lists the labels actually in force on that line, which is the fastest route to a correct payload:

{
  "error": "validation_error",
  "message": "line 319297B1622392262026T (product ZZTEST5-SEZ-DRY-SPLIT) has no size ZZZ",
  "details": {
    "purchase_line_pk": "319297B1622392262026T",
    "valid_sizes": "XS, S, M, L, XL, 2XL, 3XL, 4XL, 5XL, 6XL, 7XL"
  }
}

Note valid_sizes is a comma-separated string, not an array — split on ", " if you need a list.

Size labels are per line, not per product. A purchase line keeps its own snapshot of its size labels from when it was raised, so if the product's size group has changed since, the line still uses the old labels — and those are what size_desc is matched against. Do not source these from the current product record; use valid_sizes.

On PUT /v1/purchase-orders/receipt

A validation failure has written nothing. Every line is checked before any record is touched.

Over-receipt carries the figures, so the caller can decide without a second read:

{
  "error": "validation_error",
  "message": "line 321054O0843487132026K size M: received 5 is more than the 3 ordered - send allow_over_receipt:true if that really arrived",
  "details": { "purchase_line_pk": "321054O0843487132026K", "size": "M", "received": 5, "maximum": 3 }
}

maximum is what was ordered for that size (still on order + already received). Re-send with allow_over_receipt: true only if that quantity really arrived.

502 upstream_error

The upstream system responded, but the response was not the expected shape — e.g. a missing field, malformed JSON, an unknown error value, or an unexpected server-side exception. details may carry a diagnostic when one is available.

{
  "error": "upstream_error",
  "message": "Upstream system returned an unexpected response"
}

Client action: do not auto-retry. This almost always indicates a data or processing issue that won't self-heal. Alert / escalate. If the same payload works later, it was a one-off transient; if it repeats, report it to the API provider.

The exceptions where a 502 is actionable

PUT /v1/purchase-orders/lines — retry with the identical body. A write-phase failure there can leave earlier products written, and that endpoint's idempotency (it syncs desired state, so re-sending converges) is what makes the retry safe. Retry once; if it fails again, escalate.

PUT /v1/purchase-orders/receipt — check details.retry_same_payload. When it is true (upstream_code: "write_failed"), the write stopped part-way: details.lines_written lines were received, each completely (a line and its product counters are saved together), and the PO's invoice number may not be stored yet. Re-send the identical body: received quantities are totals, so the finished lines come back changed: false and the rest are written. Retry once; if it fails again, escalate. When it is false, do not retry.

POST /v1/purchase-orders/shipments — check details.resumable. A shipment split is not idempotent, so a blind retry is never correct; the flag tells you which of the two situations you are in.

{
  "error": "upstream_error",
  "message": "Record locked. Re-send the same payload with resume:true to finish it.",
  "details": {
    "upstream_code": "write_failed",
    "resumable": true,
    "po_no": "P23176",
    "purchase_line_pk": "31929300124606262026I",
    "lines_moved": 0
  }
}

details.po_no, details.purchase_line_pk and details.lines_moved are what let you tell a "nothing happened" 502 from a "half done" one. details.upstream_code is the raw upstream code, provided for diagnostics and alert routing — branch on resumable, not on the code string.

Without resume a half-finished shipment can never be completed through the API, because the shipment_ref guard refuses every subsequent attempt with a 409. This is the one and only case in which that flag should be set.

503 upstream_unavailable

The API could not reach the upstream system. Usually transient (restart, network blip), sometimes sustained (planned maintenance).

{
  "error": "upstream_unavailable",
  "message": "Upstream service is temporarily unavailable"
}

Client action: retry with exponential backoff — e.g. 1s, 4s, 16s, 64s, then give up and surface to the user. Do not retry-loop with no backoff; the upstream gets worse under contention, not better.

On POST /v1/orders: outcome_unknown

Creating an order is the one call where giving up early is not the same as nothing happening. When the upstream does not answer within the order-creation timeout, the API does not simply report a failure: it looks the order up by your order_no, and if the order was created you get the normal 201 with its our_ref. Only if it still cannot find it do you get:

{
  "error": "upstream_unavailable",
  "message": "The upstream system did not answer in time, so the order may or may not have been created. Look it up by order_no before retrying. Re-sending the same order_no is safe: it returns 409 if the order exists.",
  "details": { "reason": "outcome_unknown" }
}

Client action: look the order up with GET /v1/orders?order_no=… before doing anything else. If it is there, use it. If not, re-send the identical request. Re-sending is safe either way, because a second order with the same order_no is refused with 409 duplicate_reference, and that message names the existing order.

An order placed on behalf of another contact (contact_id) may not be visible to your token, in which case the lookup cannot find it and you get outcome_unknown even though it was created. The 409 on re-send still protects you.

Exception: GET /api/products uses a legacy error shape

The product-catalogue endpoint GET /api/products is the one endpoint that does not use the canonical envelope above. For backwards compatibility with existing clients, it returns:

{ "error": true, "error_reason": "Unauthorised" }

• error is a boolean (true), not an error-code string.
• error_reason is a human string. Observed values: Unauthorised (the bearer key is not recognised), and style parameter is no longer supported (the deprecated ?style= parameter, which now returns 400).

This endpoint's auth model is also different: the Authorization: Bearer <key> header is a customer token that returns that customer's pricing. No token returns the default catalogue with RRP pricing. A success returns the catalogue JSON directly, not a wrapped envelope.

Statuses this API does not emit

Last updated: 2026-09-15.