NetBox REST API POST retries create duplicate objects when unique constraints are incomplete

Direct Answer

No, NetBox (through current 3.x and 4.x releases) does not provide an Idempotency-Key header, query parameter, or any documented mechanism that makes POST create endpoints idempotent. Each POST is processed independently, so a retried request after a transient failure will create a second object unless the data model itself enforces uniqueness on the submitted fields.

Confirmed Behavior by Model Type

Models with enforced unique constraints

Examples: Device (name per site), IPAddress (address per VRF/prefix), Prefix (prefix per VRF). A retried POST on these returns 400 Bad Request with a validation error referencing the duplicate unique field. Clients can treat this specific error as "already created," then issue a filtered GET (e.g., GET /api/dcim/devices/?name=foo&site=bar) to retrieve the existing object and continue.

Models without comprehensive unique constraints

Examples: Cable, VirtualMachine, Module, ModuleBay, many custom-model endpoints. These allow multiple objects with identical user-supplied fields. A retried POST silently succeeds and creates a duplicate.

Application-Level Pattern for Non-Unique Models

The reliable pattern without external locking services is client-generated deterministic marker + database-enforced uniqueness on that marker:

1. Choose a marker field that NetBox indexes and can enforce uniqueness on. The most portable option is a Custom Field with unique=True (supported on most models in NetBox 3.5+). Alternative: a Tag with a client-controlled namespace (e.g., client-request-id:abc123), but tags are not uniqueness-enforced, so this only narrows the race window—it does not eliminate it.
2. Generate a deterministic ID per logical create operation (UUIDv4, ULID, or hash of the business key). Include it in the POST payload under the chosen marker field.
3. On transient failure (network error, 5xx, timeout), retry the identical POST. If the first attempt committed, the database rejects the second with a 400 unique-constraint violation on the marker field. Parse that error, then GET by the marker (GET /api/.../?cf_client_request_id=abc123) to recover the created object.
4. On success, the response contains the new object; cache its NetBox ID keyed by your marker for future idempotent lookups.

This moves concurrency arbitration to the database, eliminating the GET-then-POST race window.

Bulk Create Endpoints

Bulk endpoints (POST /api/.../bulk_create/) accept arrays and return per-item results, but a partial failure leaves no built-in way to know which items committed. Two practical approaches:

• Split batches to single-item requests using the marker pattern above. Throughput cost is modest; reliability gain is significant.
• If batching is required, after a partial failure, query by the marker values you sent (GET /api/.../?cf_client_request_id=abc123,def456) to identify committed items, then retry only the missing markers.

Project Roadmap Signal

As of the current release line, the NetBox project has not announced or merged native Idempotency-Key support for 4.x. Public GitHub discussions and release notes show the expectation remains that clients implement deduplication externally—either via natural keys where they exist, or via the custom-field marker pattern described above. Treat any claim of imminent native support as unverified until it appears in a release candidate.

Verification Steps for Your Version

1. Send two identical POSTs to a constrained endpoint (duplicate device name in a site). Confirm the second returns 400 with a uniqueness error you can map to the existing object via filtered GET.
2. Create a custom field client_request_id with unique=True on a non-unique model (e.g., Cable). POST with a marker value, simulate a retry, and confirm the second POST fails with a unique-constraint error on that custom field.
3. Check GET /api/dcim/cables/?cf_client_request_id=test123 returns exactly one object after the simulated retry.
4. Review the NetBox release notes and GitHub issues for your target version (e.g., netbox-community/netbox#12345 search for "idempotency") before finalizing your design.

One Diagnostic Detail That Changes the Recommendation

Does your NetBox version allow unique=True on custom fields for the specific models you need to protect? If yes, use the custom-field marker pattern. If no (older versions or models where custom-field uniqueness is not enforced), you must either add a natural unique key to the data model (e.g., a composite unique constraint via a NetBox plugin or upstream PR) or route creates through an idempotent intermediary service that deduplicates on your request ID before calling NetBox.