The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
When a WordPress REST API request says a slug already exists, first determine whether the request is creating a new item or updating an existing one. Then identify whether the target is a post or a taxonomy term and inspect the full API response. A duplicate post slug by itself does not establish that WordPress core generated that exact error; plugins, custom code, or another validation layer may be responsible.
1. Capture the full REST API response
Do not diagnose the issue from a client-side toast or a paraphrased error. Record the HTTP status, response JSON, error code and message, request method, endpoint path, and submitted payload. These details help distinguish a server response from a client-side validation message and provide the evidence needed to trace the failure.
2. Confirm what kind of WordPress object the request targets
Check whether the endpoint is for a post, page, custom post type, category, tag, or another taxonomy term. WordPress handles post slugs and term slugs through different core functions: post insertion uses wp_unique_post_slug(), while taxonomy-term insertion has separate duplicate handling in wp_insert_term(). A conflict involving a term should not be treated as a post conflict.
3. Determine whether the request is creating or updating
The WordPress posts REST resource has a collection route for posts and item routes for individual posts. A request to the collection is used to create an item; to edit an existing post, target that specific item instead. See the WordPress REST API posts reference for the resource routes and supported operations.
#1 Best Overall
WordPress’s wp_insert_post() documentation states: “If the $postarr parameter contains an ‘ID’, the corresponding post will be updated.” A request that repeatedly creates through the collection can therefore behave differently from an intended update to a known post ID.
4. Find the existing record before changing anything
Search within the intended post type for the slug and title. Include drafts and other statuses your account is allowed to see, since the conflicting item may not be publicly visible. Confirm the record’s ID and that it is the item you intend to edit before changing or deleting content.
5. Update the existing item by ID when appropriate
If the existing record is the one you want, send the update to its item route using an HTTP method supported for that operation, with authentication and permissions appropriate to the site. The WordPress REST API documentation explains its authentication methods; the credentials and user permissions required depend on the site and request.
6. Choose a distinct slug only for genuinely new content
If you intend to create a separate item, choose a meaningful slug that distinguishes it from the existing record. WordPress core post processing passes the requested post name through wp_unique_post_slug() to produce a unique post name. Appending a number or changing the slug without checking the request can mask an accidental duplicate-create operation.
7. Investigate custom behavior if the response still reports a conflict
The available WordPress references establish core post and term handling, but they cannot identify the source of an error on an unknown installation. Compare the structured response code and message with the endpoint and target type, then inspect relevant plugins, custom REST callbacks, post-type registration, and hooks that validate or change slugs. Where possible, reproduce the request on a staging copy rather than disabling or changing production behavior blindly.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.8. Retry once and verify the saved item
After correcting the target or payload, make one deliberate retry. Verify the returned post ID, slug, and final URL. Do not send blind retries: the first request may have succeeded even if the client misread its response, and another create request could add further content.
Quick Recap
Best Value
How to narrow down the cause
| What to compare | What to check | Why it matters |
|---|---|---|
| Create or update | Collection route versus item route; whether the request identifies an existing item | A create request and an update to a known item are different operations in the posts REST resource. |
| Object type | Post, page, custom post type, or taxonomy term | Post and term slugs follow different core handling paths. |
| Error origin | Core response versus plugin, custom endpoint, or client-side validation | The phrase “slug already exists” alone does not identify which layer produced it. |
| Request evidence | HTTP status, response JSON, error code and message, method, endpoint, and payload | The full request and response are needed to investigate the specific failure. |
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
