Researched guidance: How should a 409 expose the existing canonical object for safe duplicate avoidance?

Summary

For a duplicate-create 409, expose the existing object through a documented problem-details extension containing an opaque identifier and an absolute, authorized GET URI; optionally repeat that URI as a typed related link. Do not overload type, instance, Location, canonical, or duplicate semantics. Separate an in-flight idempotency conflict from a completed duplicate: the IETF draft recommends a problem-described 409 while processing and replay of the completed result, whereas GoCardless documents a completed 409 carrying links.conflicting_resource_id.

Candidate action

Return 409 Conflict with Content-Type application/problem+json and a stable problem type for the duplicate-create condition. The body should contain a short stable title, a non-sensitive detail, and an extension such as existing_resource (or conflicting_resource) with an opaque id, an absolute href for the canonical GET representation, and, if useful, a machine-readable reason. Define the extension in the problem-type documentation and require clients to ignore unknown extensions. The href must be tenant/authorization checked and must resolve to the existing canonical object; do not put the object URI in instance, because instance identifies the problem occurrence, not the conflicting resource. Do not use Location to point at the existing object in a 409: RFC 9110 gives Location's created-resource semantics to 201 and redirection semantics to 3xx. Do not use rel=duplicate for a dynamic or POSTable object; the IANA registry limits that relation to byte-identical static representations. If emitting a header link, use Link with rel=related (or a documented extension link) as an optional convenience, while keeping the body extension authoritative. For a request whose same idempotency key is still processing, return a problem-described 409 and, when an availability estimate exists, document Retry-After; do not claim an existing object until one is committed. Once the operation is complete, either replay the stored result as recommended by the IETF draft or, if the API's documented policy is a 409, return the existing_resource link/id as GoCardless does. Clients should treat a 409 with an existing href as a duplicate resolution, GET that URI, and not blindly retry the create.

Applicability

• HTTP POST create endpoints with a uniqueness or idempotency conflict that can be mapped to an existing object.
• Use the existing-object disclosure only when the caller is authorized to learn that object exists and to GET its representation; otherwise return a generic conflict without an identifying URI.
• Use a distinct in-flight conflict representation when the original idempotent request has not completed; an in-flight request has no canonical object to expose yet.

Key findings

• 409 means the request could not be completed because of conflict with the target resource's current state, and the response should contain enough information to recognize the source of the conflict. (S1)
• RFC 9457 assigns type to the problem type, instance to the individual problem occurrence, and permits documented extension members, including machine-usable typed links; clients must ignore extensions they do not recognize. (S2)
• The Idempotency-Key draft recommends 409 with a problem description while the original request is still processing, and recommends returning the previously completed result for a duplicate after completion. (S3)
• GoCardless provides a concrete product pattern for a completed 409: errors[0].links.conflicting_resource_id contains the already-created resource identifier. (S4)
• HTTP Location points to the primary resource created by a 201 or the redirection target for 3xx; the IANA duplicate relation is expressly for static byte-identical representations and should not be used for dynamic or POSTable resources. (S1, S5)

Known limitations

• RFC 9110 and RFC 9457 define the status and problem-details framework but do not standardize an existing-resource property name or require a canonical-object URI in a 409.
• The IETF Idempotency-Key draft recommends replaying the previously completed result for a completed duplicate, while GoCardless documents a product-specific completed 409 with links.conflicting_resource_id; an API must choose and document one policy.
• A URI or identifier in a conflict can disclose cross-tenant existence or sensitive relationships; authorization, tenant scoping, and stable identifier policy are implementation responsibilities.

Obsolete approaches

• Do not parse detail text to find the existing object; RFC 9457 says extensions are the suitable machine-readable mechanism.
• Do not use instance as the existing object's URI; it identifies the specific problem occurrence.
• Do not use rel=duplicate for dynamic or POSTable resources, and do not treat canonical as a general duplicate-object relation.

Negative results

• No interoperable standard was found that mandates a field such as existing_resource, conflicting_resource_id, or a 409 Location header for duplicate creation.
• The idempotency draft specifies the 409 problem shape for a request still in progress but leaves the existing-resource identifier format unspecified.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false
• This result is based on reading standards and official API documentation; no endpoint behavior was executed or independently reproduced.

What remains unknown

• The target API's exact conflict taxonomy, extension naming convention, idempotency-key retention window, and whether its canonical href is guaranteed to remain readable are not specified in the brief.
• It is unknown whether the target API permits the caller to learn that an object exists across authorization or tenant boundaries; this must be decided by its security model.
• It is unknown whether clients of the target API expect completed idempotency retries to replay the original response or to receive a 409 with an existing-object reference.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 RFC 9110: HTTP Semantics · standard · accessed 2026-09-22
• S2 RFC 9457: Problem Details for HTTP APIs · standard · accessed 2026-09-22
• S3 The Idempotency-Key HTTP Request Header Field (Internet-Draft) · standard · accessed 2026-09-22
• S4 Safely retrying API requests - GoCardless · official_documentation · accessed 2026-09-22
• S5 IANA Link Relations · standard · accessed 2026-09-22