How Eight Failed API Runs Revealed a Hidden State Machine in MiroFish Integration

A developer integrating with the MiroFish simulation API encountered repeated failures across eight successive attempts before achieving a complete, working call sequence. Each failure exposed a distinct contract mismatch, including a Redis misconfiguration, duplicate records, mixed synchronous and asynchronous response models, and deeply nested payload structures. The core problem was that the API behaved as a strict state machine — requiring simulation creation, profile preparation, run initiation, and explicit report triggering as separate ordered steps — despite appearing as simple HTTP endpoints. Once the true sequence was understood, the developer replaced a single generic response decoder with per-operation normalizers that enforce the specific payload shapes observed in live runs. The integration was ultimately stabilized by treating a full lifecycle execution as a contract test, with verified response fixtures anchoring future decoder validation.