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 invalid.",
  "status": 400,
  "code": "validation_error",
  "detail": "One or more fields are invalid.",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "errors": [{
    "path": "items.0.vin",
    "code": "invalid_length",
    "message": "The VIN must contain 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 retry action

Result	Action
Network timeout	Retry a write with the same idempotency key.
`429`	Wait for `Retry-After`, then retry.
`500` to `599`	Retry with exponential backoff and jitter.
`invalid_client`	Stop and check the credential and environment.
`validation_error`	Correct the named fields.
`request_too_large`	Reduce the body. Do not retry the same body.
`revision_conflict`	Read the order, then decide from the new revision.
`idempotency_conflict`	Use the original body or a new key for a new write.
`order_not_updateable` or `order_not_cancellable`	Read `allowed_actions` and stop the action.

Set a maximum retry count. Do not retry a permanent 4xx error without a request change.

Use idempotency keys

Order commands and file-upload creation need an Idempotency-Key. File deletion is idempotent without this header. Create one key for one logical write. Reuse the same key after a timeout or server error. Use a new key for a new logical write. Do not reuse a key with a different body.

Use order revisions

Order update and cancellation requests need If-Match. Set it to the current order revision. Read the order again after a revision conflict. Do not overwrite a newer order without a new decision. 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

Core integration

Customer features

Platform integrations

Test and automate

Errors, retries, and conflicts

Read a problem response

Choose a retry action

Use idempotency keys

Use order revisions

Store request IDs

​Read a problem response

​Choose a retry action

​Use idempotency keys

​Use order revisions

​Store request IDs

Read a problem response

Choose a retry action

Use idempotency keys

Use order revisions

Store request IDs