Skip to main content

Errors

Every error from the API is a problem in the RFC 7807 format, sent as application/problem+json. This guide explains its fields, the kinds of error you meet, and what to do about each.

The fields of a problem​

{
"type": "https://orderex.io/problems/vat-required",
"title": "Vat Required",
"status": 422,
"detail": "Every new order needs pricesIncludeVat and every new line a vatRate.",
"instance": "/api/v1/orders",
"errors": {
"pricesIncludeVat": [
"pricesIncludeVat is required: true when the prices include VAT, false when they exclude it."
]
},
"correlationId": "4bf92f3577b34da6a3ce929d0e0e4736",
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}
FieldWhat it holds
typeWhat went wrong, as a stable address. Act on this, not on title or detail
titleA short name for type
statusThe HTTP status code
detailWhat went wrong in this request, for a person to read
instanceThe path that was called
errorsThe fields that were wrong, each with its messages, when the problem is about fields
correlationId and traceIdThe ids OrderEx support uses to find your request

Some problems carry more fields, such as existingOrderId, existingFact, rules or replacedBy. The table below names them.

400, 422 and 401​

StatusWhat it meanserrors keys
400 with type https://tools.ietf.org/html/rfc9110#section-15.5.1A field breaks a rule of the request's format, such as a required field that is missing, a text that is too long or a negative unit priceValidator names, mostly PascalCase, such as CustomerId or Lines[0].VatRate
400 invalid-requestThe body could not be read, such as broken JSON or an amount sent as a stringNone
422The request is well formed, but OrderEx cannot accept it, such as a missing VAT rate or a shipment above what is orderedThe body's own field names, camelCase, such as pricesIncludeVat or lines[1].vatRate
401The X-Api-Key header is missing, or the key is wrong, expired or revokedNone

A 400 for a field that breaks a format rule has the title Validation Error and no correlationId. A 401 has only type, title, status and traceId.

Problem types and what to do​

type ends inStatusWhat to do
invalid-request400Send valid JSON, with amounts as numbers
unsupported-currency422Use SEK, NOK, DKK, EUR, GBP, USD or ISK
vat-required422Send pricesIncludeVat, and vatRate on every line. errors names each missing field
invalid-amount422Send amounts as whole numbers in minor units, see Core concepts
order-already-exists409The order is already created. Use existingOrderId, or the Location header
idempotency-key-reused409The key was used for another body. Use a new key for a new request
fact-conflict409Another fact has the same id. Compare existingFact with what you sent, and fix the source
concurrency-conflict409Another change to the same order happened at the same moment. Send the same request again
order-not-modifiable409The order is in a final status of your status flow and cannot be changed
order-not-found404Check the order id. An order of another tenant is not found either
order-line-not-found404Check the line id against lines of the order
parcel-not-found404Check the parcel id against the order's shipments
shipment-not-found404Check the shipment id against the order's shipments
occurred-at-in-future422Send the time with its offset, and check your clock. It may be at most 5 minutes ahead of OrderEx
line-quantity-rule-violated422The fact would break a rule between the line's quantities. rules names it, such as returned-exceeds-shipped. Report the missing fact first
shipment-node-unknown422Register the node, or use the id of one of your nodes
shipment-line-not-on-order422Ship only lines of this order. orderLineIds names the others
payment-currency-mismatch422Use the order's currency, given in orderCurrency
payment-allocation-invalid422Fix the allocations. reasons says what is wrong
unknown-payment-fact-type422Use one of the types in allowed
unknown-payment-method422Use one of the methods in allowed
quantity-reported-as-fact422Report the quantity as a fact instead, with the call in replacedBy
endpoint-closed422The endpoint is closed. Use the one in replacedBy
order-status-change-rejected422Your status flow does not allow the change. detail says why
status-flow-not-found404Your tenant has no status flow. Contact OrderEx
node-name-taken409Give the node a name your other nodes do not have
node-not-found404Check the node id with GET /api/v1/fulfillment/nodes
webhook-not-found404Check the webhook id with GET /api/v1/webhooks

Every type is an address under https://orderex.io/problems/, such as https://orderex.io/problems/fact-conflict. When you meet a type your client does not know, handle it by its status code, as the versioning policy asks.

When you need help​

Quote the problem's correlationId or traceId when you contact OrderEx about a failed request, together with the time and the call. With them, OrderEx can find your request. For a problem without either, send the time, the call and the body you sent, without your API key.

Next​

Webhooks lets OrderEx tell your systems when an order changes.