Errors
Every error has the same envelope: { "error": "<code>", "message": "…", "details": { … } }. Branch on error, never on message; details.path names the field when one is at fault.
Paths, field names, error codes, header names and code samples stay in English: they are the contract.
When to retry
429 and 503 come with a Retry-After header: wait that many seconds and send the same request again. 504 solve_timeout may succeed on a retry with a smaller job. Every 4xx other than 429 is a problem with the request itself and fails again unchanged.
Codes
| Code | Status | Meaning |
|---|---|---|
| invalid_request | 400 | The body or a parameter is malformed: not JSON, not an object, or a field of the wrong shape. |
| idempotency_key_required | 400 | The order call has no valid Idempotency-Key header. |
| quote_invalid | 400 | The quote token does not belong to this quote, has expired or was changed, or test and live were mixed. |
| unknown_workflow | 400 | The shop has no workflow with this id. |
| workflow_disabled | 400 | The workflow exists but is switched off. |
| mode_mismatch | 400 | The mode sent is not the mode of this workflow. |
| unknown_mode | 400 | The mode sent is not a known mode. |
| unsupported_mode | 400 | The workflow's mode is not available on this service yet. |
| limit_exceeded | 400 | Too many or too few rows, too many parts, or a part outside the shop's size limits. |
| outside_catalog_slice | 400 | A material is not offered in this workflow. |
| unknown_reference | 400 | A material, edging or other catalogue item is unknown or switched off. |
| required_field_missing | 400 | A field the shop marked as required is missing. |
| unauthorized | 401 | The key is missing, malformed, unknown or revoked, or a test key has expired. |
| project_token_required | 401 | A project call needs the project token header. |
| project_token_invalid | 401 | The project token header is malformed or was sent twice. |
| quota_exceeded | 402 | The shop's monthly quote allowance is used up. |
| customer_context_required | 403 | A customer group other than the default needs the secret key, so a call from your server. |
| origin_not_allowed | 403 | The page's origin is not on the publishable key's list. |
| sandbox_expired | 403 | The sandbox shop has expired and is read-only. |
| not_found | 404 | No such route, quote, order or project, or one that belongs to another shop. |
| not_configured | 404 | The shop has not published a configuration yet. |
| idempotency_conflict | 409 | This Idempotency-Key was already used for a different quote. |
| quote_already_redeemed | 409 | This quote has already been ordered. |
| quote_requote | 409 | The quote was signed with a key that has since been rotated: request a new quote. |
| too_large | 413 | The request body is larger than the route accepts. |
| unsupported_media_type | 415 | The body was not sent as application/json. |
| plan_incomplete | 400 / 422 | Some parts do not fit on any sheet, so there is nothing to quote. |
| project_not_reorderable | 422 | The saved project holds no cut list that can be priced. |
| rate_limited | 429 | A rate limit was reached: wait for the seconds in Retry-After. |
| busy | 429 | The solver queue is full: retry after the seconds in Retry-After. |
| test_limit | 429 | Test keys reached their daily quote or order ceiling. |
| sandbox_order_limit | 429 | The sandbox shop reached its order ceiling for the period. |
| project_limit | 429 | The shop already stores the maximum number or size of saved projects. |
| internal | 500 | An unexpected error on our side. |
| service_unavailable | 503 | A part of the service did not answer: try again later. |
| config_invalid | 503 | The shop's configuration cannot be loaded. |
| tenant_unconfigured | 503 | The shop has no active quote-signing key. |
| final_engine_unavailable | 503 | This workflow quotes on the max engine, which is not available here. |
| solve_timeout | 504 | The plan took too long. |
Pricing codes
These codes come from the pricing engine. They answer 400 on POST /cfg/v1/quote and on a reorder; on POST /cfg/v1/preview the call succeeds and the code arrives in priceError, so the live preview can show the plan while the price cannot be computed.
invalid_config · invalid_job · invalid_request · unknown_workflow · workflow_disabled · unknown_mode · mode_unavailable · unsupported_mode · unknown_reference · item_disabled · outside_catalog_slice · unpriced_item · no_strategy · unpriced_sheet · cut_length_unattributable · plan_incomplete · bonded_unpriced · bonded_not_allowed · template_value_invalid · machining_length_missing · machining_invalid · unknown_customer_group · shipping_unavailable · delivery_below_minimum · weight_unavailable · rule_budget · amount_overflow
There is no "try it" button here on purpose: the secret key belongs on your server, never in a browser. The demo shop shows the embed and the order hand-off working end to end.
LegalConfigurator terms ·Data processing agreement ·Shopper privacy notice ·Third-party licences