validation-failedCopy Anchor Link

HTTP 400 or 422.

• 400: the request reached the endpoint but one or more parameters did not match its schema.
• 422: the request was well formed, but Supliful refuses what it asks for. POST /v1/orders answers this way when a product is not orderable through your connection (errors[].path lines.productId), when the shipping address would fail at label creation (errors[].path shippingAddress, one entry per issue), or when a product cannot be fulfilled yet (no errors, only detail). A sandbox transition the test order's state does not allow answers 422 too.

Read the status before the errors array: a 400 is a bug in your request, a 422 is a decision about the order. Show address issues to the buyer.

Unlike most problem types, this one can carry an extra errors array naming each field that failed — permitted by RFC 9457 §3.2, which allows additional members on a problem document.

{
  "type": "https://developers.supliful.com/errors/validation-failed",
  "title": "Request validation failed",
  "status": 400,
  "detail": "One or more request parameters are invalid.",
  "instance": "/v1/example",
  "errors": [
    { "path": "quantity", "message": "Expected number, received string" },
    { "path": "address.zip", "message": "Required" }
  ]
}

Reading the errors arrayCopy Anchor Link

Each entry has:

• path — the location of the offending value, dot-joined. Nested objects read as address.zip; array members include their index, as lines.0.sku.
• message — what was wrong with that specific value.

The array names every field that failed, not just the first, so a single round trip tells you everything you need to correct. There is no need to fix one field and resubmit to discover the next.

How to fix itCopy Anchor Link

Read the path values against the endpoint's schema in the API Reference, which is generated from the same definitions that perform this validation — so the reference and the validator cannot disagree.

The usual causes:

• A number sent as a string, typically from a template or a form encoding ("3" where 3 is expected).
• A missing required field, reported as Required.
• A timestamp not in ISO 8601 form.
• A field name that is close but not exact — casing and pluralisation are significant.

Retry behaviourCopy Anchor Link

Terminal. The same request will fail identically until the payload changes, so do not retry it unmodified. Log the errors array — it is the whole diagnosis, and it is not recoverable from the status code alone.