Why We Reserve Credits Before Running an Image Editing Job A developer at PicViva, a product photo editor, described a credit-reservation architecture that holds credits when an image-editing job is accepted, charges them on success, and releases them on terminal failure. The design pairs client-generated idempotency keys, scoped per workspace and enforced with a database unique constraint, with a conditional SQL update that checks available balance in the same statement that creates the hold. Task creation and reservation commit in one transaction, and the terminal task transition settles accounting atomically so retried deliveries cannot double-charge. You click Start editing and the request times out. You hit Retry. A few seconds later, the image processor reports that the job failed. That one interaction raises three questions. Did the first request create a job? Could a second request spend the same credits? What happens to the credits when the job fails? PicViva https://picviva.ai/en is a product photo editor. Take a background removal job as an example: the editor can accept the request and return a task ID while the image is still processing. If the user retries before seeing that ID, the backend needs a way to recognize the original submission. A credit reservation makes those questions easier to answer. The API holds credits when it accepts a job. The worker turns that hold into a charge when the job succeeds, or releases it when the job reaches a terminal failure. Have the client generate an idempotency key when the user submits an edit. If the response is lost, resend the request using that same key. An intentional second edit gets a fresh key, even if it uses the same image and settings. On the server, scope the key to the workspace and enforce uniqueness in the database. A lookup can handle the common case where the original request already committed. The unique constraint handles the race where two requests both pass the lookup. Resolve a duplicate to the existing task when it represents the same operation. If your API also stores a request fingerprint, it can reject reuse of the key with different parameters. The task row is the receipt. Once the API has it, the client can poll that task ID to find out what happened. Suppose a workspace has 10 credits, and two different jobs each ask for 7. Both requests might read an available balance of 10 before either writes. Put the check in the statement that creates the hold so it uses the current balance when the database applies the update. UPDATE credit accounts SET reserved balance = reserved balance + :cost WHERE workspace id = :workspace id AND balance - reserved balance = :cost; Here, balance is the settled balance and reserved balance is the amount currently on hold. The SQL uses illustrative named parameters. For a positive-cost job with an existing account, one affected row means the reservation succeeded. In the example, the first update leaves 3 available. The other update affects zero rows because it needs 7. Create the task row and record the reservation in the same transaction. If the reservation fails, roll back the task insert too. Make the job eligible for dispatch after commit so a worker can see the task and the hold together. php Client API / database Worker |-- submit -- create task + hold 7 | | commit and make job runnable --- | |-- retry --- return the same task ID | | |-- process image | success: charge 7, clear hold <--| | or | | failure: clear hold only <------| Starting from a balance of 10 with 7 reserved, here's how the terminal outcomes differ. | Event | Balance | On hold | Available | |---|---|---|---| | Task accepted | 10 | 7 | 3 | | Task succeeded | 3 | 0 | 3 | | Task failed | 10 | 0 | 10 | The last two rows are alternative outcomes from the accepted state. On success, the worker lowers both the balance and the held amount. On terminal failure, it only lowers the held amount. The available balance stays at 3 on success because those 7 credits were already unavailable while the job was running. I’d put the terminal task transition and its accounting update in one transaction. A conditional transition from the expected state gives the worker a way to tell whether this delivery is still allowed to settle the task. That matters if the worker commits a result and then loses the acknowledgement. The job may be delivered again, and a repeated completion must leave the balance alone. Keep the hold in place while an internal retry is still pending. There’s also a gap between a database commit and sending work to a separate queue. If the process dies in that gap, a committed task can sit with credits reserved and nothing running. A transactional outbox or a recovery scan for committed, undispatched tasks can close that gap. If you’ve built a job queue with prepaid credits, how do you recover holds for jobs that never reach a worker?