Hoppa till huvudinnehåll

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 each problem type means and what to do about it.

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 catalogue 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.

The catalogue of problem types​

Every OrderEx type is an address under https://orderex.io/problems/, such as https://orderex.io/problems/fact-conflict, and the table names it by the part after problems/. The two types from RFC 9110 are named by their whole address.

TypeStatusMeaningWhat to do
https://tools.ietf.org/html/rfc9110#section-15.5.1400A field breaks a rule of the request's format. errors names each field and ruleFix the fields errors names and send the request again
https://tools.ietf.org/html/rfc9110#section-15.5.2401The request has no X-Api-Key, or the key is wrong, expired or revokedDo not retry. Check the key your system sends, and ask OrderEx for a new one if it was revoked
invalid-request400The body could not be read, such as broken JSON or an amount sent as a stringSend valid JSON, with amounts as numbers
unsupported-currency422The order's currency is not one OrderEx supportsUse SEK, NOK, DKK, EUR, GBP, USD or ISK
vat-required422The order has no pricesIncludeVat, or a line has no vatRate. errors names each missing fieldSend pricesIncludeVat, and vatRate on every line
invalid-amount422An amount is not a whole number in minor units, or does not fitSend amounts as whole numbers in minor units, see Core concepts
order-already-exists409An order with the same channel and externalOrderNumber exists. existingOrderId and Location point at itUse the existing order. Do not create it again
idempotency-key-reused409The Idempotency-Key was used before with another bodyUse a new key for a new request
fact-conflict409Another fact has the same id with other content. existingFact is the fact OrderEx hasCompare existingFact with what you sent, and fix the source
concurrency-conflict409Another change to the same order was stored at the same momentSend the same request again
order-not-modifiable409The order is in a final status of your status flowDo not change the order. Report facts, which every status accepts
order-not-found404No order of your tenant has the id. An order of another tenant is not found eitherCheck the order id
order-line-not-found404The order has no line with the idCheck the line id against lines of the order
parcel-not-found404No shipment of the order has a parcel with the idCheck the parcel id against the order's shipments
shipment-not-found404The order has no shipment with the idCheck the shipment id against the order's shipments
occurred-at-in-future422A time is more than 5 minutes after OrderEx's clock. errors names the fieldSend the time with its offset, and check your clock
line-quantity-rule-violated422The fact would break a rule between the line's quantities. rules names it, such as returned-exceeds-shipped, and nothing is storedReport the missing fact first, then send this one again
shipment-node-unknown422nodeId is not one of your fulfillment nodesRegister the node, or use the id of one of your nodes
shipment-line-not-on-order422A shipment names a line that is not on the order. orderLineIds names itShip only lines of this order
payment-currency-mismatch422A payment fact is in another currency than the order. orderCurrency is the order'sUse the order's currency
payment-allocation-invalid422The allocations of a payment fact are wrong. reasons says howFix the allocations
unknown-payment-fact-type422type of a payment fact is not one OrderEx knows. allowed lists themUse one of the types in allowed
unknown-payment-method422paymentMethod is not one OrderEx knows. allowed lists themUse one of the methods in allowed
quantity-reported-as-fact422A deprecated call tried to change a quantity that facts report. replacedBy names the callsReport the quantity as a fact, with the call in replacedBy
endpoint-closed422The endpoint is closed. replacedBy names what replaces itUse the endpoint in replacedBy
order-status-change-rejected422Your status flow, or one of its validation rules, does not allow the change. detail says whyMove the order along a transition your flow has
status-flow-not-found404Your tenant has no status flowContact OrderEx
node-name-taken409Another of your fulfillment nodes has the nameGive the node a name your other nodes do not have
node-not-found404You have no fulfillment node with the idCheck the node id with GET /api/v1/fulfillment/nodes
webhook-not-found404You have no webhook with the idCheck the webhook id with GET /api/v1/webhooks
control-not-activated409Control is not activated for your tenantWait until GET /api/v1/control says Control is active
control-not-migrated503Control is not set up for your tenant yetSend the request again later
imbalance-not-found404You have no imbalance with the id. An imbalance of another tenant is not found eitherCheck the imbalance id with GET /api/v1/control/imbalances
imbalance-resolved409The imbalance is resolved, which is final, and takes no other statusRead the imbalance again. Do not change its status
assessment-running409An assessment of your imbalances is running. Retry-After says when to try againSend the request again after the seconds in Retry-After
user-not-found404The portal user of the session no longer exists. Only the portals call GET /api/v1/auth/meNothing for an integration, which never calls the auth endpoints

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.