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"
}
| Field | What it holds |
|---|---|
type | What went wrong, as a stable address. Act on this, not on title or detail |
title | A short name for type |
status | The HTTP status code |
detail | What went wrong in this request, for a person to read |
instance | The path that was called |
errors | The fields that were wrong, each with its messages, when the problem is about fields |
correlationId and traceId | The 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
| Status | What it means | errors keys |
|---|---|---|
400 with type https://tools.ietf.org/html/rfc9110#section-15.5.1 | A 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 price | Validator names, mostly PascalCase, such as CustomerId or Lines[0].VatRate |
400 invalid-request | The body could not be read, such as broken JSON or an amount sent as a string | None |
| 422 | The request is well formed, but OrderEx cannot accept it, such as a missing VAT rate or a shipment above what is ordered | The body's own field names, camelCase, such as pricesIncludeVat or lines[1].vatRate |
| 401 | The X-Api-Key header is missing, or the key is wrong, expired or revoked | None |
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.
| Type | Status | Meaning | What to do |
|---|---|---|---|
https://tools.ietf.org/html/rfc9110#section-15.5.1 | 400 | A field breaks a rule of the request's format. errors names each field and rule | Fix the fields errors names and send the request again |
https://tools.ietf.org/html/rfc9110#section-15.5.2 | 401 | The request has no X-Api-Key, or the key is wrong, expired or revoked | Do not retry. Check the key your system sends, and ask OrderEx for a new one if it was revoked |
invalid-request | 400 | The body could not be read, such as broken JSON or an amount sent as a string | Send valid JSON, with amounts as numbers |
unsupported-currency | 422 | The order's currency is not one OrderEx supports | Use SEK, NOK, DKK, EUR, GBP, USD or ISK |
vat-required | 422 | The order has no pricesIncludeVat, or a line has no vatRate. errors names each missing field | Send pricesIncludeVat, and vatRate on every line |
invalid-amount | 422 | An amount is not a whole number in minor units, or does not fit | Send amounts as whole numbers in minor units, see Core concepts |
order-already-exists | 409 | An order with the same channel and externalOrderNumber exists. existingOrderId and Location point at it | Use the existing order. Do not create it again |
idempotency-key-reused | 409 | The Idempotency-Key was used before with another body | Use a new key for a new request |
fact-conflict | 409 | Another fact has the same id with other content. existingFact is the fact OrderEx has | Compare existingFact with what you sent, and fix the source |
concurrency-conflict | 409 | Another change to the same order was stored at the same moment | Send the same request again |
order-not-modifiable | 409 | The order is in a final status of your status flow | Do not change the order. Report facts, which every status accepts |
order-not-found | 404 | No order of your tenant has the id. An order of another tenant is not found either | Check the order id |
order-line-not-found | 404 | The order has no line with the id | Check the line id against lines of the order |
parcel-not-found | 404 | No shipment of the order has a parcel with the id | Check the parcel id against the order's shipments |
shipment-not-found | 404 | The order has no shipment with the id | Check the shipment id against the order's shipments |
occurred-at-in-future | 422 | A time is more than 5 minutes after OrderEx's clock. errors names the field | Send the time with its offset, and check your clock |
line-quantity-rule-violated | 422 | The fact would break a rule between the line's quantities. rules names it, such as returned-exceeds-shipped, and nothing is stored | Report the missing fact first, then send this one again |
shipment-node-unknown | 422 | nodeId is not one of your fulfillment nodes | Register the node, or use the id of one of your nodes |
shipment-line-not-on-order | 422 | A shipment names a line that is not on the order. orderLineIds names it | Ship only lines of this order |
payment-currency-mismatch | 422 | A payment fact is in another currency than the order. orderCurrency is the order's | Use the order's currency |
payment-allocation-invalid | 422 | The allocations of a payment fact are wrong. reasons says how | Fix the allocations |
unknown-payment-fact-type | 422 | type of a payment fact is not one OrderEx knows. allowed lists them | Use one of the types in allowed |
unknown-payment-method | 422 | paymentMethod is not one OrderEx knows. allowed lists them | Use one of the methods in allowed |
quantity-reported-as-fact | 422 | A deprecated call tried to change a quantity that facts report. replacedBy names the calls | Report the quantity as a fact, with the call in replacedBy |
endpoint-closed | 422 | The endpoint is closed. replacedBy names what replaces it | Use the endpoint in replacedBy |
order-status-change-rejected | 422 | Your status flow, or one of its validation rules, does not allow the change. detail says why | Move the order along a transition your flow has |
status-flow-not-found | 404 | Your tenant has no status flow | Contact OrderEx |
node-name-taken | 409 | Another of your fulfillment nodes has the name | Give the node a name your other nodes do not have |
node-not-found | 404 | You have no fulfillment node with the id | Check the node id with GET /api/v1/fulfillment/nodes |
webhook-not-found | 404 | You have no webhook with the id | Check the webhook id with GET /api/v1/webhooks |
control-not-activated | 409 | Control is not activated for your tenant | Wait until GET /api/v1/control says Control is active |
control-not-migrated | 503 | Control is not set up for your tenant yet | Send the request again later |
imbalance-not-found | 404 | You have no imbalance with the id. An imbalance of another tenant is not found either | Check the imbalance id with GET /api/v1/control/imbalances |
imbalance-resolved | 409 | The imbalance is resolved, which is final, and takes no other status | Read the imbalance again. Do not change its status |
assessment-running | 409 | An assessment of your imbalances is running. Retry-After says when to try again | Send the request again after the seconds in Retry-After |
user-not-found | 404 | The portal user of the session no longer exists. Only the portals call GET /api/v1/auth/me | Nothing 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.