Orders and Latency

Every change a player makes to the world is an order: queued through the API, carried to its target, and resolved by the tick.

The tick

The world advances one tick at a time. Only the tick changes the world; the API reads it and queues orders.
Durations in the data are written in minutes and turned into ticks by tick_scale, so they keep their real-time length.
Each tick runs its steps in a fixed order: orbits, world rules, arrivals, jobs, packets, orders, mail, fights, relays, reports, standing orders, sightings.
A ship or facility has one job at a time. A finished job leaves it idle until another order arrives.
GET /v1/status gives the current tick.

Each verb has its own endpoint, such as POST /v1/fleet/ships/{id}/move or POST /v1/fleet/stations/{id}/facilities/{facility_id}/produce.
The response gives the order id, tick_due and arrives_tick: when the order resolves if nothing holds it up. Null means no route reaches the ship or station yet.
GET /v1/orders and GET /v1/orders/{id} show each order's state: in_flight, then completed, failed or cancelled.
A failed order carries error_code and error_reason. A rule violation fails an order before anything changes.
Orders due in the same tick resolve oldest first.
source names the trigger or schedule that sent an order, such as trigger:unload. sent_by names the player or company whose key sent it.

Every order carries an Idempotency-Key header.
Resending a key returns the first order and queues nothing. Resending it with a different order is a 409 idempotency_conflict.
A key belongs to one order while the order is kept: reusing it after that order resolved returns the old order.
A finished order and its packets are deleted 30 days after it was sent. Its key is then free again.

Every order endpoint takes ?dry_run=true. The order's rules run against the world as it is now, then everything rolls back.
An order that would pass returns order: null. One that would fail returns a 409 with its rejection code.
A move or jump also returns arrival_tick and fuel, and a move the meeting point at.
The world can change before the real order resolves.

An order to a ship, station or facility travels as a packet through its owner's Infonet. An order to a facility goes to its station.
Orders to the hull resolve next tick, since the hull is a command post. So do orders to command nodes and companies, which send no packet of their own.
Orders start at the hull. A packet leaves from a command post the hull's own network reaches; a post cut off from the hull sends nothing.
An order to a ship, station or facility in a system where its side has a command post linked to the hull is local. It sends no packet and resolves next tick, with no hops and no depth delay. A station that is such a post is local to itself. A ship jumping is in no system.
A packet crosses one link between relays per hop. Queues at busy relays, detours and waits make it later, and arrives_tick moves to match.
Once delivered, an order to a ship waits a further delay set by the ship's depth in its owner's chain of command: none directly under the hull, more for each level of command nodes. Stations are not in the chain of command, so an order to one resolves on delivery.
A ship or station beyond every relay its side can use, its own and those leased or open to it, receives nothing until it is back in range. Meanwhile it runs only the standing orders it already has, until it is fetched or a relay comes within reach.
GET /v1/infonet/packets lists packets in flight: the relay each is at, the next one, and its state (new, queued, moving or waiting).

DELETE /v1/orders/{id} takes back an order in flight. Only the key that sent it, or a key above it in the chain of control, can (not_your_order).
An order sent this tick, still at its first command post, or waiting with no way on, is cancelled at once.
An order already travelling to a ship or station gets a recall: a packet of its own, from the linked command post nearest its target, with recall_arrives_tick.
A recall that takes effect before its order cancels it. One that arrives in the same tick or later is too late, and the order runs. order.recalled says which.
An order has at most one recall (already_recalled). An order no longer in flight cannot be recalled (not_in_flight).

POST /v1/fleet/orders sends one verb to every ship in a saved group, a ship query or a command node. See Command.
Each matched ship gets an ordinary order with its own packet, which passes or fails by itself. GET /v1/orders?batch= lists them.
A group or query fixes its ships when the order is sent. A node reads its members when the order resolves.
POST /v1/fleet/orders/expand returns the ship orders a group order would make, with a dry run of each, and queues nothing. The list, edited or not, goes to POST /v1/fleet/orders as {"orders": [...]}.
One Idempotency-Key covers a whole group order.

Every error body is {"detail": {"code": ..., "reason": ...}}.
A 422 without a code is a request that does not match the schema.
A server fault inside one order fails only that order, with internal_error. The rest of the tick goes on.