Errors

The error envelope

Every error under /api/v1 uses the same structure:

{
  "error": {
    "code": "not_found",
    "message": "The requested resource does not exist.",
    "details": []
  }
}

• code is a stable, machine-readable identifier. Base your handling on it.
• message is for people and written in English. It can change at any time. Do not parse it.
• details is either an empty list [] or an object with additional information. Its content depends on the code.

Status codes and error codes

Status	error.code	Cause	What to do
401	unauthorized	Key missing, invalid, paused, expired or revoked. The reason is never stated.	Check the key, ask the operator
403	insufficient_scope	Key is valid but lacks a scope. details.required and details.missing list the scopes.	Ask the operator to add the scope
403	forbidden	Access denied	Do not retry, ask the operator
404	not_found	Path or resource does not exist, the customer is not linked to your key, or the API is not enabled for this shop	Check the path and IDs
405	method_not_allowed	Wrong HTTP method for this path	Use the documented method
409	order_deleted	An order with this external_order_id existed but has been deleted	Do not retry, inform the operator
409	conflict	The request conflicts with the current state	Do not retry unchanged
422	validation_failed	The data is invalid. details lists every problem per field.	Fix the data, then send again
422	client_not_configured	The access is not fully set up: no shop, shop deleted, or the default referrer is inactive or not assigned to the shop	Inform the operator
429	rate_limited	Too many requests, or too many failed authentication attempts	Wait for Retry-After seconds, then retry
500	server_error	Unexpected error on the shop’s side	Retry later; if it persists, give the operator details.reference if present
other 4xx/5xx	request_failed	The request could not be processed	Check the request; retry 5xx later

A complete list of all codes, including field-level codes, is in the error code reference.

Field errors

validation_failed lists all problems at once, not only the first. details is an object keyed by field name. Each field holds a list of { code, message } entries:

{
  "error": {
    "code": "validation_failed",
    "message": "The order was not created.",
    "details": {
      "items.1.sku": [{ "code": "unknown_article", "message": "Article 'SKU-9999' is not known." }],
      "payment_method_id": [
        {
          "code": "unknown_payment_method",
          "message": "Payment method 99 does not exist or is inactive."
        }
      ]
    }
  }
}

Field names use dots for nesting. items.1.sku is the field sku of the second item, because list positions count from 0. customer.billing.postcode is the postcode of the billing address.

Customer endpoints use the same structure, with the general message The request payload is invalid.

The field codes fall into a few groups:

• Format: required, invalid_format, too_long, out_of_range, invalid_value, duplicate_value
• Unknown references: unknown_payment_method, unknown_referrer, unknown_order_status, unknown_country, unknown_customer, unknown_article, unknown_value
• Not offered: payment_method_not_available (the payment method exists but is not offered in your client’s shop, or the customer is not approved for the collective invoice; use an ID from listPaymentMethods)
• Business rules: unsupported_currency, required_for_packstation, customer_address_incomplete, ambiguous_article, article_inactive, article_tax_unresolved, article_reserved

Each code is described in the error code reference. If you receive a field code you do not know, treat it like invalid_format: the field needs correcting.

Nothing is created on error

If the API answers with an error, nothing was created or changed by that request. For orders this means: no order, no customer, no stock reservation. You can fix the data and send the same request again.

Server errors

An unexpected error answers 500 with server_error. When an order could not be created, details.reference contains an identifier the operator can use to find the case:

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred. The order was not created.",
    "details": { "reference": "2f0c6a52-6a8e-4c1e-9d0e-0b7f3c8a1e44" }
  }
}

Retry later with unchanged data. See Retries and duplicate protection.

Maintenance

During maintenance the shop answers 503 Service Unavailable with the header X-App-Maintenance: 1. This is the only response that does not use the error envelope:

{
  "message": "Service Unavailable"
}

Make sure your error handling does not fail when error is missing. Treat 503 like any other temporary error and retry later.

Warnings

Some problems do not stop an order. The order is created, and the response lists them in warnings, for example no_shipping_method or collective_invoice_single_order. See Send an order.