Errors, retries, and conflicts

V2 resource errors use application/problem+json. The OAuth token endpoint uses standard OAuth error responses. Branch on the stable code, not the human-readable message. Include the request_id when you contact Bahn support.

Read a problem response

{
  "type": "https://api.bahnexpress.fi/problems/validation-error",
  "title": "The request is not valid.",
  "status": 400,
  "code": "validation_error",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "errors": [{
    "path": "items.0.vin",
    "code": "too_small",
    "message": "Too small: expected string to have exactly 17 characters"
  }]
}

The errors array can identify more than one invalid field. Do not parse the human message to select a program action.

Choose a recovery action

Result	Action
Network timeout	Retry the same logical write with the same key and request data.
`401` from a resource request	Get a fresh token and retry once. Stop if it still fails.
`429`	Respect `Retry-After` when present, otherwise use backoff.
`500` to `599`	Retry with exponential backoff and jitter. Preserve write keys and request data.
OAuth `invalid_client`	Stop and check the credential and environment.
OAuth `invalid_request`	Check the content type, grant, and requested scopes.
`permission_denied`	Check granted scopes and access to the resource.
`resource_not_found`	Check the ID, environment, and account. An inaccessible order can also return this code.
`validation_error`	Correct the named fields.
`request_too_large` or `file_too_large`	Reduce the body or file. Do not retry it unchanged.
`revision_conflict` (`412`)	Read the order, then decide from its new revision and actions.
`idempotency_conflict` (`409`)	Check the original operation, request data, and whether its first attempt is still in progress.
`order_not_updateable` or `order_not_cancellable`	Read `allowed_actions` and stop the unavailable action.
`business_rule_violation`	Read `detail` to explain why Bahn cannot serve the request as written.
`ordered_for_not_allowed`	Use an ordering-channel credential if the order belongs to another business. Omit the field only for an own-account order.
`ordered_for_customer_not_found`	Check the business ID and country code, then contact support.
`scenario_not_allowed`	Check the test order’s state and the scenario preconditions.

Set a maximum retry count and surface a failure when it is exhausted. A token refresh is the limited recovery path for a resource 401. Other permanent 4xx errors need a corrected request, permission, or account setup.

Use idempotency keys

Order creation, updates, cancellation, file-upload creation, and sandbox advancement require Idempotency-Key. Price checks and represented-business checks do not require it. File deletion is idempotent without the header. Use a unique key of 8 to 255 characters for each logical write. Keys are shared across write operations for the authenticated customer account, so a cancellation must not reuse an order-creation key. Store the key with the method, resource path, and request data. After a timeout, retry that request rather than starting another write. For an update or cancellation, preserve the original If-Match too. A retry of a completed order write does not perform the write again, but it can return the order’s current state. Do not assume that the response is an identical historical snapshot. After idempotency_conflict, check your stored request before changing anything. A new key is appropriate for a new logical write. It is not a way to recover an unknown result from a timed-out creation.

Use order revisions

Order updates and cancellation require If-Match. Put the current order revision inside double quotation marks:

If-Match: "7qS4Jd1cKx9Nw2Yh6mVb8Pz0Rt3Fu5AeLgCiEoUaWQk"

After revision_conflict, read the order again. Decide whether the original change is still appropriate, check allowed_actions, and use a new key for the newly decided write. Do not automatically overwrite another person’s change. A live ETA update does not change the order revision.

Store request IDs

You can send X-Request-ID. The response also includes a request ID. Store the request ID with each write result. Send it to support@bahnexpress.com when you report a problem.

Get started

Create and manage orders

Follow the transport

Reliability and production

Platform ordering

Automation

Errors, retries, and conflicts

Read a problem response

Choose a recovery action

Use idempotency keys

Use order revisions

Store request IDs

​Read a problem response

​Choose a recovery action

​Use idempotency keys

​Use order revisions

​Store request IDs

Read a problem response

Choose a recovery action

Use idempotency keys

Use order revisions

Store request IDs