Errors

The API uses conventional HTTP status codes and returns a consistent JSON error body.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Product 10020000213575 price mismatch: expected 10000"
}

statusCode

integer

The HTTP status code.

error

string

A short, machine-friendly label for the status (for example Bad Request, Not Found).

message

string

A human-readable explanation you can show to operators or log for support. When a message refers to a product, it uses the productCode you sent in the request.

Placeholders below use {productCode}, {reference}, {min}, {max}, {expected}, {productCurrency}, {requested}, and {seconds} for values that depend on your request. All other text is returned exactly as shown.

Status codes

Code	`error` label	When it applies
`400`	`Bad Request`	Validation before or during order placement (price, currency, catalog membership, product configuration)
`401`	`Unauthorized`	Missing or invalid `x-api-key`
`403`	`Forbidden`	API ordering disabled for your account
`404`	`Not Found`	Unknown catalog product or order
`409`	`Conflict`	Duplicate `externalOrderCode`
`422`	`Unprocessable Entity`	Account order limit exceeded, insufficient wallet funds, or product not available for purchase
`429`	`Too Many Requests`	Rate limit exceeded
`502`	`Bad Gateway`	Order could not be created or is temporarily unavailable
`500`	—	Unexpected server error

Authentication (`401`)

Message
`Missing API key`
`Invalid API key`

See Authentication for examples.

Rate limiting (`429`)

Message
`Rate limit exceeded. Retry after {seconds}s.`

The Retry-After response header matches {seconds}. See Rate limits.

Catalog (`404`)

Returned by GET /catalog/products/{productCode} when the productCode is not in your active catalog.

Message
`Product {productCode} was not found in your catalog`

Orders - request validation (`400`)

Returned by POST /orders when the request body fails checks before the order is accepted.

Message
`orderProducts must not be empty`
`Each line requires a productCode and a quantity of at least 1`
`Product {productCode} is priced in {productCurrency}, not {requested}`
`Product {productCode} is open-denomination and requires a price`
`Price for product {productCode} is below the minimum allowed ({min})`
`Price for product {productCode} exceeds the maximum allowed ({max})`
`Product {productCode} price mismatch: expected {expected}`
`Order price mismatch: expected total {expected}`

Prices in mismatch and denomination messages are in minor units (same as the catalog), e.g. 10000 = 100.00.

Orders - rejected at placement (`400`)

Returned by POST /orders when the order cannot be accepted after validation.

Typical situation	Message
Product not orderable for country/currency	`Product {productCode} is not available for ordering with the supplied country or currency.`
Product inactive	`Product {productCode} is not currently available.`
Wrong order currency	`Product {productCode} cannot be ordered in the requested currency.`
Open denomination, price missing	`Product {productCode} is open-denomination and requires a price.`
Order data invalid	`The order could not be validated. Check product codes, prices, and currency.`
Order already placed	`This order has already been placed.`
Other rejection	`The order could not be placed. Check your request and try again.`

Order each product for the market shown in the catalog (countryCode). Mismatched country or currency often surfaces as “not available for ordering with the supplied country or currency”.

Orders - forbidden (`403`)

Message
`API ordering is disabled for your account. Contact support for assistance.`

Orders - conflict (`409`)

Message
`An order with this external order code already exists.`

Orders - unprocessable (`422`)

Message
`Your account order limit has been exceeded. Contact support for assistance.`
`Insufficient funds. Please top up your wallet and try again.`
`Product {productCode} is not available for purchase.`

Orders - not found (`404`)

Returned by GET /orders/{reference}.

Message
`Order {reference} not found`

{reference} is the path value you sent (the UUID orderId or your externalOrderCode).

Orders - bad gateway (`502`)

Returned when the order cannot be created or processing is temporarily unavailable.

Message
`Order processing is temporarily unavailable. Please try again later.`
`Order could not be created. Please try again later.`

Server errors (`500`)

Returned when an unexpected error occurs. Retry with backoff; contact support if the problem persists.

Message
`Internal server error`

The error field is omitted on some 500 responses.

Handling errors in your integration

Log statusCode and message

Persist both fields for support and retries. Treat message as human-readable text.

Map by productCode

When message starts with Product {productCode}, attach the error to that line in your cart or order payload.

Retry only when appropriate

Retry 502 and 429 with backoff. Do not retry 400, 403, 404, 409, or 422 without fixing the request.

Refresh catalog on configuration errors

If you see “not available for ordering with the supplied country or currency”, re-fetch the product from GET /catalog/products and verify countryCode, price, and open-denomination bounds.

Get started

Core concepts

Migrate

Status codes

Authentication (`401`)

Rate limiting (`429`)

Catalog (`404`)

Orders - request validation (`400`)

Orders - rejected at placement (`400`)

Orders - forbidden (`403`)

Orders - conflict (`409`)

Orders - unprocessable (`422`)

Orders - not found (`404`)

Orders - bad gateway (`502`)

Server errors (`500`)

Handling errors in your integration

​Status codes

​Authentication (401)

​Rate limiting (429)

​Catalog (404)

​Orders - request validation (400)

​Orders - rejected at placement (400)

​Orders - forbidden (403)

​Orders - conflict (409)

​Orders - unprocessable (422)

​Orders - not found (404)

​Orders - bad gateway (502)

​Server errors (500)

​Handling errors in your integration

Status codes

Authentication (`401`)

Rate limiting (`429`)

Catalog (`404`)

Orders - request validation (`400`)

Orders - rejected at placement (`400`)

Orders - forbidden (`403`)

Orders - conflict (`409`)

Orders - unprocessable (`422`)

Orders - not found (`404`)

Orders - bad gateway (`502`)

Server errors (`500`)

Handling errors in your integration