From c8f797aafef6ce3848755329297a2adbc1cc40c2 Mon Sep 17 00:00:00 2001
From: Eric Allam <eallam@icloud.com>
Date: Tue, 14 Apr 2026 14:46:50 +0100
Subject: [PATCH] fix(run-engine): distinguish oneTimeUseToken P2002 from
 idempotency key collision

---
 internal-packages/run-engine/src/engine/index.ts | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/internal-packages/run-engine/src/engine/index.ts b/internal-packages/run-engine/src/engine/index.ts
index a1446d54b2..720264e0b7 100644
--- a/internal-packages/run-engine/src/engine/index.ts
+++ b/internal-packages/run-engine/src/engine/index.ts
@@ -46,7 +46,7 @@ import { RunQueue } from "../run-queue/index.js";
 import { RunQueueFullKeyProducer } from "../run-queue/keyProducer.js";
 import { AuthenticatedEnvironment, MinimalAuthenticatedEnvironment } from "../shared/index.js";
 import { BillingCache } from "./billingCache.js";
-import { NotImplementedError, RunDuplicateIdempotencyKeyError } from "./errors.js";
+import { NotImplementedError, RunDuplicateIdempotencyKeyError, RunOneTimeUseTokenError } from "./errors.js";
 import { EventBus, EventBusEvents } from "./eventBus.js";
 import { RunLocker } from "./locking.js";
 import { getFinalRunStatuses } from "./statuses.js";
@@ -709,15 +709,25 @@ export class RunEngine {
             });
 
             if (error.code === "P2002") {
-              this.logger.debug("engine.trigger(): throwing RunDuplicateIdempotencyKeyError", {
+              const target = (error.meta as Record<string, unknown>)?.target;
+              const targetFields = Array.isArray(target) ? target : [];
+
+              this.logger.debug("engine.trigger(): P2002 unique constraint violation", {
                 code: error.code,
                 message: error.message,
                 meta: error.meta,
+                target: targetFields,
                 idempotencyKey,
                 environmentId: environment.id,
               });
 
-              //this happens if a unique constraint failed, i.e. duplicate idempotency
+              if (targetFields.includes("oneTimeUseToken")) {
+                throw new RunOneTimeUseTokenError(
+                  `One-time use token has already been used`
+                );
+              }
+
+              // Only idempotency key collisions should be retried
               throw new RunDuplicateIdempotencyKeyError(
                 `Run with idempotency key ${idempotencyKey} already exists`
               );