diff --git a/src/main/java/com/faforever/api/achievements/AchievementUpdateRequest.java b/src/main/java/com/faforever/api/achievements/AchievementUpdateRequest.java
index 649e52458..dc84752d1 100644
--- a/src/main/java/com/faforever/api/achievements/AchievementUpdateRequest.java
+++ b/src/main/java/com/faforever/api/achievements/AchievementUpdateRequest.java
@@ -1,10 +1,13 @@
 package com.faforever.api.achievements;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 record AchievementUpdateRequest(
   int playerId,
   String achievementId,
   Operation operation,
-  int steps
+  @Schema(description = "Required for INCREMENT and SET_STEPS_AT_LEAST; ignored (and may be null/omitted) for REVEAL and UNLOCK.", nullable = true)
+  Integer steps
 ) {
   public enum Operation {
     REVEAL, UNLOCK, INCREMENT, SET_STEPS_AT_LEAST
diff --git a/src/main/java/com/faforever/api/achievements/AchievementsController.java b/src/main/java/com/faforever/api/achievements/AchievementsController.java
index abf753428..f324edc82 100644
--- a/src/main/java/com/faforever/api/achievements/AchievementsController.java
+++ b/src/main/java/com/faforever/api/achievements/AchievementsController.java
@@ -21,9 +21,16 @@ public void update(AchievementUpdateRequest request) {
     switch (request.operation()) {
       case REVEAL -> throw new UnsupportedOperationException("REVEAL is not yet implemented");
       case UNLOCK -> achievementService.unlock(request.playerId(), request.achievementId());
-      case INCREMENT -> achievementService.increment(request.playerId(), request.achievementId(), request.steps());
+      case INCREMENT -> achievementService.increment(request.playerId(), request.achievementId(), requireSteps(request));
       case SET_STEPS_AT_LEAST ->
-        achievementService.setStepsAtLeast(request.playerId(), request.achievementId(), request.steps());
+        achievementService.setStepsAtLeast(request.playerId(), request.achievementId(), requireSteps(request));
     }
   }
+
+  private static int requireSteps(AchievementUpdateRequest request) {
+    if (request.steps() == null) {
+      throw new IllegalArgumentException("steps is required for operation " + request.operation());
+    }
+    return request.steps();
+  }
 }