Fix ‘slug already exists’ in WordPress REST API explained

Introduction

Most of the time, this error means a draft, trashed post, or term is already using that slug — not a REST API bug. Here’s how to locate the collision quickly, clear it properly, and make your POST or PUT succeed without touching core.

Understanding the slug collision problem

Slug conflicts can arise across post types and taxonomies. The REST API uses unique slugs to fetch the correct resource, so duplicates disrupt data retrieval.

Why it matters for WordPress REST API operations

Accurate slugs ensure predictable API responses for cities, categories, or products. A unique slug set reduces errors and speeds up automated workflows.

Step by Step Solution: Check Slug Availability

Using wp_unique_post_slug to generate a unique slug

WordPress provides wp_unique_post_slug to return a slug that does not exist in the database. Pass the desired slug, post type, and optional post ID to ensure uniqueness across the targeted content. This function checks existing posts, pages, and custom post types and can integrate with a REST API workflow.

• Call wp_unique_post_slug with the intended slug
• Specify the post type to scope the check
• If the slug exists, use the returned unique variant

Alternative method: direct database slug check

You can query the wp_posts table to verify if a slug already exists for a given post type. Use a direct SQL check and then decide whether to modify the slug or append a numeric suffix to guarantee uniqueness.

• Query wp_posts where post_name equals the intended slug
• Filter results by post_type as needed
• If a match exists, generate a new slug variant and recheck

Step by Step Solution: Choose the Right Post Type Scope

Identify the post type or taxonomy causing the collision

Map where the collision occurs. It could be a post, a page, a custom post type, or a taxonomy term. Review the API responses to see which content type is referenced and if the slug is used across multiple content types. This keeps the REST API workflow predictable.

• Examine the API error payload for post_type or taxonomy indicators
• Check recent creations or updates that might have introduced the duplicate
• Note whether the slug appears in wp_posts or term relationships

Scope the slug check to the correct content type

Limit slug validation to the targeted content type to prevent cross type conflicts. Use the correct query or function arguments so the check applies only to posts, pages, or specific taxonomies.

• Specify post_type in wp_unique_post_slug calls or SQL queries
• Filter taxonomy slug checks to a single taxonomy when applicable
• Document the scope to maintain consistent checks in automation

Step by Step Solution: Clean Up Duplicates and Conflicts

Remove or rename conflicting posts or terms

Identify items sharing the same slug across posts, pages, and taxonomies. Rename or reassign conflicting items to restore unique slugs. Recheck REST API endpoints after changes. Keep a clear naming convention to prevent future collisions and document changes for audits.

• Search for duplicate post_name values in wp_posts
• Rename conflicting items to new, descriptive slugs
• Rebuild permalinks to apply changes

Handle hierarchical taxonomies and parent relationships

In hierarchical taxonomies, a child term may collide with a sibling or parent slug. Break the collision by adjusting parent term slugs or reorganizing term hierarchies. Ensure each term path remains unique and update references in posts or products that rely on those slugs.

• Review term relationships in wp_terms and wp_term_taxonomy
• Adjust parent or child slugs to maintain uniqueness
• Update related posts or products to reflect new slugs

FAQ

What causes a slug exists error in the WordPress REST API

• Multiple content types share the same slug such as posts, pages, or custom post types
• Taxonomy terms use the same slug as a post or page
• Existing drafts or revisions block slug reuse until published

How can I test a slug quickly

• Use wp_unique_post_slug to generate a unique variant for the targeted post type
• Run a direct database check on wp_posts for the post_name value if needed

What should I do after renaming or moving a slug

• Rebuild permalinks and verify REST API endpoints
• Update related content references to reflect the new slug

Conclusion

Solving the WordPress REST API slug exists issue comes down to verifying slug uniqueness within the correct post type scope, cleaning duplicates, and validating changes in the REST responses. Use a mix of built in checks and careful cleanup to keep slugs unique long term.