# UNIQUE_VIOLATION — composite unique key constraint violated

The entity payload contains field values that collide with an existing entitys composite unique key. Unlike an optimistic-concurrency CONFLICT (which is …

<em>cyoda-go version <a href="https://github.com/Cyoda/cyoda-go/releases/tag/v0.8.2">0.8.2</a></em>

# errors.UNIQUE_VIOLATION

## NAME

UNIQUE_VIOLATION — a write was rejected because it would create a duplicate entry for a declared composite unique key.

## SYNOPSIS

HTTP: `409` `Conflict`. Retryable: `no`.

## DESCRIPTION

The entity payload contains field values that collide with an existing entity's composite unique key. Unlike an optimistic-concurrency CONFLICT (which is retryable), a unique-key violation is a permanent data constraint — retrying the same payload without changing the key field values will produce the same result.

To resolve: change the values of the fields that form the unique key so they no longer duplicate an existing entity.

On write-time backends (PostgreSQL) this can also fire within one transaction when a value is claimed before its holder is freed; free-before-claim is portable (see `cyoda help models`).

## SEE ALSO

- errors
- errors.CONFLICT
- errors.INVALID_UNIQUE_KEY

## See also

- [`cyoda help errors`](/help/errors/) — Every error response from the Cyoda REST API carries a structured `errorCode` in the `properties` object. Multiple codes may share the same HTTP status. Programmatic handling keys on `errorCode`, not HTTP status.
- [`cyoda help errors CONFLICT`](/help/errors/conflict/) — The server detected that the entity was modified by another writer between the time it was read and the time the current write was committed. Normal outcome under concurrent load.
- [`cyoda help errors INVALID_UNIQUE_KEY`](/help/errors/invalid_unique_key/) — A composite unique key requires every declared field to be present and non-null. This error is returned when the entity payload is missing a value for at least one key field, or the value cannot be normalized to a valid claim (for example, a NaN or ±Infinity for a numeric key field).

## Raw formats

- [`/help/errors/unique_violation.json`](/help/errors/unique_violation.json) — full descriptor (matches `GET /help/{topic}` envelope)
- [`/help/errors/unique_violation.md`](/help/errors/unique_violation.md) — body only