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"
}
| 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 table 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.
Problem types and what to do
type ends in | Status | What to do |
|---|---|---|
invalid-request | 400 | Send valid JSON, with amounts as numbers |
unsupported-currency | 422 | Use SEK, NOK, DKK, EUR, GBP, USD or ISK |
vat-required | 422 | Send pricesIncludeVat, and vatRate on every line. errors names each missing field |
invalid-amount | 422 | Send amounts as whole numbers in minor units, see Core concepts |
order-already-exists | 409 | The order is already created. Use existingOrderId, or the Location header |
idempotency-key-reused | 409 | The key was used for another body. Use a new key for a new request |
fact-conflict | 409 | Another fact has the same id. Compare existingFact with what you sent, and fix the source |
concurrency-conflict | 409 | Another change to the same order happened at the same moment. Send the same request again |
order-not-modifiable | 409 | The order is in a final status of your status flow and cannot be changed |
order-not-found | 404 | Check the order id. An order of another tenant is not found either |
order-line-not-found | 404 | Check the line id against lines of the order |
parcel-not-found | 404 | Check the parcel id against the order's shipments |
shipment-not-found | 404 | Check the shipment id against the order's shipments |
occurred-at-in-future | 422 | Send the time with its offset, and check your clock. It may be at most 5 minutes ahead of OrderEx |
line-quantity-rule-violated | 422 | The 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-unknown | 422 | Register the node, or use the id of one of your nodes |
shipment-line-not-on-order | 422 | Ship only lines of this order. orderLineIds names the others |
payment-currency-mismatch | 422 | Use the order's currency, given in orderCurrency |
payment-allocation-invalid | 422 | Fix the allocations. reasons says what is wrong |
unknown-payment-fact-type | 422 | Use one of the types in allowed |
unknown-payment-method | 422 | Use one of the methods in allowed |
quantity-reported-as-fact | 422 | Report the quantity as a fact instead, with the call in replacedBy |
endpoint-closed | 422 | The endpoint is closed. Use the one in replacedBy |
order-status-change-rejected | 422 | Your status flow does not allow the change. detail says why |
status-flow-not-found | 404 | Your tenant has no status flow. Contact OrderEx |
node-name-taken | 409 | Give the node a name your other nodes do not have |
node-not-found | 404 | Check the node id with GET /api/v1/fulfillment/nodes |
webhook-not-found | 404 | Check 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.