You're collaborating with a teammate on an important document. You open it to make some crucial edits, and just as you're about to save, you get a message: "This document is currently locked by another user. Please try again later." Instead of frustration, you feel relief that you just avoided overwriting your colleague's work thanks to a clever system that prevented a conflict.
This collaborative safety net is powered by one of HTTP's more specialized status codes: 423 Locked. This code isn't about security or permissions in the traditional sense; it's about preventing conflicts in collaborative environments.
The 423 status code is the server's way of saying, "I can't let you modify this resource right now because someone else is already working on it. Please wait your turn." It's the digital equivalent of a "Do Not Disturb" sign on a hotel room door or seeing someone else's cursor actively typing in a shared Google Doc.
But don’t worry by the end of this post, you’ll not only understand what it means, but you’ll also know why it happens, how to fix it, and how to avoid it in the future.
And if you’re an API developer or tester, I'll show you how tools like Apidog can make detecting and resolving 423 errors much easier.
If you work with collaborative editing tools, version control systems, or any application where multiple users might conflict with each other, understanding 423 is incredibly valuable.
Now, let's explore the world of resource locking and the HTTP 423 status code.
The Problem: The Dangers of Concurrent Editing
To understand why 423 exists, we need to understand the problem of concurrent modification. Imagine two users, Alice and Bob, both editing the same customer record at the same time:
- 3:00:00 PM: Alice and Bob both fetch the customer record. It shows:
{"name": "John", "email": "john@old.com"} - 3:00:01 PM: Alice changes the email to
john@new.comand saves. - 3:00:02 PM: Bob changes the name to "Jonathan" and saves.
- Result: Bob's save overwrites Alice's email change because he was working with an outdated version. The final record shows
{"name": "Jonathan", "email": "john@old.com"}Alice's work is lost!
This is called a "lost update" problem, and it's a classic issue in collaborative systems. The 423 Locked status code is part of the solution.
What Does HTTP 423 Locked Actually Mean?
The 423 Locked status code is part of the WebDAV (Web Distributed Authoring and Versioning) protocol extension to HTTP. It indicates that the method (like PUT, DELETE, or PROPPATCH) could not be performed on the resource because the resource is locked.
The response should include information about the lock in the response body, typically using XML.
A typical 423 response looks like this:
HTTP/1.1 423 LockedContent-Type: application/xml; charset="utf-8"
<?xml version="1.0" encoding="utf-8"?>
<D:error xmlns:D="DAV:">
<D:lock-token-submitted>
<D:href>/workspace/doc.txt</D:href>
</D:lock-token-submitted>
</D:error>
Or a more helpful version might be:
HTTP/1.1 423 LockedContent-Type: application/json
{
"error": "ResourceLocked",
"message": "This document is currently being edited by alice@example.com",
"locked_until": "2024-01-15T14:30:00Z",
"locked_by": "alice@example.com"
}
This code originates from the WebDAV (Web Distributed Authoring and Versioning) protocol an extension of HTTP that allows users to collaboratively edit and manage files on remote servers.
In simpler terms:
A 423 Locked error occurs when a resource (like a file, object, or record) is currently “locked” by someone or something else, and your request tries to modify it.
The Official Definition (RFC 4918)
According to the RFC 4918 (which defines WebDAV):
“The 423 (Locked) status code means the source or destination resource of a method is locked.”
This means:
- The server understands your request.
- The request syntax is valid.
- But it cannot perform the operation because the targeted resource is locked.
In short: you’re not allowed to modify it right now.
Common Scenarios Where You Might See 423 Locked
Let’s go over some real-world examples where this status code pops up both in web development and API design.
1. Concurrent File Editing
If your web application allows file uploads, updates, or collaborative editing, it may use locking mechanisms to prevent conflicts.
When a file is locked (to prevent others from making simultaneous edits), any attempt to overwrite it triggers a 423.
Example:
- A document management system locks files while they’re being edited.
- Another user tries to upload changes → HTTP 423 Locked.
2. Database Record Locking
In APIs that handle sensitive data (like inventory, banking, or scheduling), records are often locked during updates to prevent race conditions.
If one transaction locks a record for modification and another request tries to update it, the second one may get a 423 Locked.
3. Version Control Systems
In systems like Git-based platforms or CMS software that support file versioning, a file or entity might be locked until a merge or approval process is complete.
Trying to push or delete during that period can trigger a 423 response.
4. API Rate Limiting or Workflow Lock
Some APIs implement temporary locks to maintain order in workflows.
For instance, a resource might be locked while it’s being processed or validated and until that’s done, new changes are blocked.
5. WebDAV File Operations
Since 423 originates from WebDAV, any operations like COPY, MOVE, DELETE, or PUT on locked resources return this status.
The Locking Mechanism: How It Works in Practice
Resource locking typically follows a specific workflow in WebDAV-compliant systems:
Step 1: Acquiring the Lock
Before editing, a client requests a lock on the resource using the LOCK method.
LOCK /documents/report.txt HTTP/1.1
Host: example.comTimeout: Second-3600Content-Type: application/xmlContent-Length: 150
<?xml version="1.0" encoding="utf-8"?>
<D:lockinfo xmlns:D="DAV:"><D:lockscope><D:exclusive/></D:lockscope><D:locktype><D:write/></D:locktype><D:owner>Alice</D:owner></D:lockinfo>
Step 2: Server Grants the Lock
The server responds with a success and provides a lock token.
HTTP/1.1 200 OKContent-Type: application/xmlLock-Token: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>
<?xml version="1.0" encoding="utf-8"?>
<D:prop xmlns:D="DAV:"><D:lockdiscovery><D:activelock><D:locktype><D:write/></D:locktype><D:lockscope><D:exclusive/></D:lockscope><D:depth>0</D:depth><D:owner>Alice</D:owner><D:timeout>Second-3600</D:timeout><D:locktoken><D:href>urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href></D:locktoken></D:activelock></D:lockdiscovery></D:prop>
Step 3: Bob Tries to Edit
While Alice has the lock, Bob tries to modify the same document.
PUT /documents/report.txt HTTP/1.1Host: example.comContent-Type: text/plain
This is Bob's attempted change.
Step 4: Server Returns 423 Locked
The server checks and finds Alice has an exclusive lock on the resource.
HTTP/1.1 423 LockedContent-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<D:error xmlns:D="DAV:"><D:lock-token-submitted><D:href>/documents/report.txt</D:href></D:lock-token-submitted></D:error>
Step 5: Alice Releases the Lock
When Alice is done editing, she explicitly unlocks the resource.
UNLOCK /documents/report.txt HTTP/1.1
Host: example.comLock-Token: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>
Types of Locks in WebDAV
WebDAV supports different locking strategies:
Exclusive Locks
Only one user can hold an exclusive lock at a time. This is the most common type and provides the strongest conflict prevention.
Shared Locks
Multiple users can hold shared locks simultaneously, but no one can get an exclusive lock while shared locks exist. This is useful for reading while preventing modifications.
423 vs. 409 Conflict: Understanding the Difference
This is an important distinction in the world of concurrent access:
423 Locked: "You can't do this because someone has explicitly locked the resource." This is a proactive, preventive measure. The system is actively preventing the conflict before it happens.409 Conflict: "You tried to make a change, but it conflicts with someone else's changes." This is reactive. The conflict has already occurred, and the server is telling you to resolve it.
Analogy:
423: You try to enter a meeting room, but there's a sign saying "Meeting in Progress - Do Not Disturb." You wait outside.409: You and a colleague both try to book the same meeting room in a scheduling system at the same time. The system tells you there's a conflict that needs resolution.
Modern Applications Beyond WebDAV
While 423 originated with WebDAV, the concept of resource locking is widely used in modern applications:
1. Collaborative Document Editors
Tools like Google Docs, Notion, and Confluence use similar locking mechanisms to show when someone else is actively editing a document.
2. Database and Record Locking
Many applications implement pessimistic locking at the database level to prevent concurrent updates to the same record.
3. E-commerce Inventory Systems
When you add an item to your cart, the system might temporarily "lock" that inventory to prevent overselling while you complete your purchase.
4. File Upload and Processing
A system might lock a file while it's being processed (e.g., virus scanning, image optimization) to prevent other operations from interfering.
423 Locked in RESTful APIs: Should You Use It?
Absolutely but with care.
In REST API design, using 423 can be beneficial when:
- A resource is undergoing a process that shouldn’t be interrupted.
- A file or object is being modified by another user.
- Temporary business logic requires "locking" behavior.
However, if you're designing APIs for broader use (outside WebDAV contexts), you might want to return 409 Conflict instead for general state conflicts since 423 is more specific.
Testing APIs with Apidog
Testing concurrent access scenarios is challenging but crucial. Apidog provides excellent capabilities for testing these complex workflows.
With Apidog, you can:
- Simulate Multiple Users: Create different requests with different authentication tokens to simulate Alice and Bob working on the same resource.
- Test Lock Acquisition: Send
LOCKrequests (if testing a WebDAV server) or your custom locking endpoint and verify you get the correct response with a lock token. - Test Lock Enforcement: Have "Alice" acquire a lock, then have "Bob" try to modify the resource and verify he receives a
423 Lockedresponse. - Test Lock Release: Verify that after "Alice" releases the lock, "Bob" can successfully modify the resource.
- Automate Locking Scenarios: Create test scenarios that automatically run through complete locking workflows to ensure your locking logic works correctly.
This is particularly valuable for applications that handle sensitive data or require strong consistency guarantees.
Best Practices for Implementing Locking
For Server Developers:
- Set Reasonable Timeouts: Always set expiration times on locks to prevent resources from being permanently locked if a client crashes or disconnects.
- Provide Clear Error Information: When returning
423, include details about who holds the lock and when it expires. - Support Lock Discovery: Allow clients to check who holds a lock and its status without trying to acquire it.
- Consider Optimistic Locking: For some use cases, optimistic locking (using version numbers or ETags) might be more efficient than pessimistic locking.
For Client Developers:
- Handle 423 Gracefully: Don't treat it as a fatal error. Inform the user that the resource is locked and provide options to retry later.
- Respect Lock Timeouts: Don't try to circumvent locks; wait for them to expire naturally or for the owner to release them.
- Release Locks Promptly: Always release locks when you're done with them to avoid blocking other users unnecessarily.
Common Misconceptions About HTTP 423
Let’s bust a few myths.
❌ “It’s a permission error.”
No that’s 403 Forbidden. 423 is temporary and resource-specific.
❌ “It means my server is down.”
Nope. Your server is fine; it’s just protecting a resource from simultaneous edits.
❌ “It only applies to WebDAV.”
While defined in WebDAV, modern REST APIs also use 423 when it fits the context.
Potential Pitfalls and Considerations
While locking is powerful, it has some challenges:
- Deadlocks: If two processes each lock a resource and then try to lock what the other has, they can deadlock.
- Performance Overhead: Managing locks adds complexity and can impact performance.
- User Experience: Poorly implemented locking can frustrate users if they're blocked for long periods.
- Stale Locks: If a client crashes without releasing its lock, the resource can remain locked until the timeout expires.
Conclusion: The Collaborative Safety Net
The HTTP 423 Locked status code represents an elegant solution to the complex problem of concurrent access. While it originated in the WebDAV protocol, the concept of resource locking is fundamental to building reliable, collaborative applications.
Understanding when and how to use locking and when to use alternative strategies like optimistic concurrency control is a key skill for developers building multi-user systems. The 423 code isn't an error to be feared; it's a feature that enables safe collaboration.
By implementing proper locking mechanisms and handling 423 responses gracefully, you can build applications that prevent data corruption and provide a smooth collaborative experience. And when you need to test these complex concurrent scenarios, a powerful tool like Apidog gives you the control and visibility to ensure your locking logic works flawlessly under real-world conditions.
