Shred a data subject (cannot be undone)

POST

/api/v2/organizations/{organization}/projects/{project}/kv/{store_id}/ledgers/{ledger_name}/shred

curl --request POST \
  --url https://dashboard.quantcdn.io/api/v2/organizations/test-org/projects/test-project/kv/test-org-test-project-orders/ledgers/aiUse/shred \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "subjectId": "user-4417", "reason": "Erasure request 2026-118", "authority": "Records authority 2023/00456 class 12", "requestedBy": "Privacy officer" }'

• QuantCDN Public Cloud
• QuantGov Cloud

Crypto-shreds the personal fields of one data subject: appends a shred entry to every collection of the ledger that holds the subject, then destroys the subject key. The entries stay on the chain; their personal fields can never be decrypted again. After fullyErasedAfter (shreddedAt + 35 days) no backup of the key remains. A 200 writes one erasure record (KV_ledgers_shreds_list) with a signed receipt (KV_ledgers_shreds_receipt); the answer has shredId, subjectRef and the receipt.\n\n202 in_progress: the time budget of this call ended before every collection had its shred entry. Send the same request again until it answers 200; no entry is written twice. The shred is safe to repeat: a repeat after a 200 answers 200 with alreadyShredded true, and a lost connection is 503 UNAVAILABLE with retryable true. 409 CONTENTION and 503 UNAVAILABLE are retryable: send the same request again.\n\nThe subject id is in the body, so it stays out of request paths and access logs; the portal audit keeps only the subjectRef of the answer (and the HMAC of requestedBy). subjectId: a string or a safe integer; the server canonicalises it (trim, NFC, the ledger’s case rule) and refuses an invalid id with VALIDATION. A SUBJECT_NOT_FOUND error has a fixed message that never names the subject. reason, authority and requestedBy: 1-1000 characters each, not only spaces; they are stored in the shred entries and the receipt.\n\nNeeds a token with the explicit kv:ledger:erase scope (full_access and tokens without a scope list cannot use it) and the ledger_erase permission. Rate limit: 30 requests per minute per project (kv-erase). Timeout 60 seconds. Audited.

Authorizations

• BearerAuth
  kv:ledger:erase

Parameters

Path Parameters

organization

required

string

Organization identifier

Example

test-org

project

required

string

Project identifier

Example

test-project

store_id

required

string

KV store id, as returned by KV_list

Example

test-org-test-project-orders

ledger_name

required

string

/^[A-Za-z][A-Za-z0-9_]{0,63}$/

Example

aiUse

Request Body^required

Media typeapplication/json

An unknown field is 400 VALIDATION. reason, authority and requestedBy must not be only spaces; they are stored in the shred entries and the signed receipt.

object

subjectId

required

One of:

string

string

>= 1 characters <= 1024 characters

integer

integer format: int64

>= -9007199254740991 <= 9007199254740991

reason

required

Why the subject is shredded.

string

>= 1 characters <= 1000 characters

authority

required

The legal authority, for example Records authority 2023/00456 class 12.

string

>= 1 characters <= 1000 characters

requestedBy

required

Who asked for the shred.

string

>= 1 characters <= 1000 characters

Example

{
  "subjectId": "user-4417",
  "reason": "Erasure request 2026-118",
  "authority": "Records authority 2023/00456 class 12",
  "requestedBy": "Privacy officer"
}

Responses

200

The subject is shredded (or was already shredded).

Media typeapplication/json

object

ledger

required

string

entries

required

The shred entry of each collection that holds the subject (empty for alreadyShredded, a DROPPED ledger and a forked store).

Array<object>

The receipt of an appended entry. Keep receipts: the offline verifier checks them against the archive.

object

key

required

Collection:id

string

id

required

ULID, a hyphen and the two-digit shard. Increases within a shard.

string

shard

required

string

/^[0-9]{2}$/

seq

required

Sequence number of the entry on its shard.

integer

>= 1

at

required

Epoch milliseconds (the ULID time of id).

integer format: int64

hash

required

SHA-256 hex of this entry.

string

/^[0-9a-f]{64}$/

prevHash

required

SHA-256 hex of the previous entry on the shard (the genesis hash for seq 1).

string

/^[0-9a-f]{64}$/

ledger

required

The ledger name.

string

source

Who wrote the entry, set by the KV service from the authenticated caller (never from the body) and covered by the entry hash. platform: a Quant service (quant-ledger writes the shred entries); api: an API caller (an append through this API with a portal token records principal token:); dashboard: a portal user (principal: the portal user id); edge: an edge function (principal //). An API caller with the API secret only records principal api-secret. Absent on entries written before provenance existed.

object

type

required

string

Allowed values: platform api dashboard edge

principal

required

string

<= 256 characters /^[A-Za-z0-9][A-Za-z0-9._:@/-]*$/

replayed

Present only on a retry with the same idempotencyKey: this is the first receipt.

boolean

shreddedAt

required

When the key was destroyed (the first shred for alreadyShredded).

string format: date-time

fullyErasedAfter

required

ShreddedAt + 35 days: after this time no backup of the key remains.

string format: date-time

alreadyShredded

Present only when the subject was shredded before this call and this call wrote nothing.

boolean

ledgerForked

Present only when the store is forked: the key is destroyed and no shred entry is recorded.

boolean

shredId

The id of the erasure record (the same on every repeat).

string

/^[0-9A-HJKMNP-TV-Z]{26}$/

subjectRef

required

The pseudonym of the subject in the erasure records and receipts.

string

/^[0-9a-f]{32}$/

refKeyVersion

required

The version of the reference key that made subjectRef.

integer

>= 1

receipt

The signed receipt of an erasure. Save the object as a file to check it with kv-ledger-verify verify-signed. Only json is signed: parse it, do not re-serialise it.

object

json

required

The RFC 8785 (JCS) text of the receipt that was signed.

string

signature

required

Base64 DER ECDSA P-256 signature over the SHA-256 of the UTF-8 bytes of json.

string

keyId

required

The KMS key ARN of the ledger key.

string

algorithm

required

string

Allowed values: ECDSA_SHA_256

Example

{
  "entries": [
    {
      "key": "ai-use:agency-1:01M5104A000000000000000000-00",
      "id": "01M5104A000000000000000000-00",
      "source": {
        "type": "platform",
        "principal": "token:42"
      },
      "replayed": true
    }
  ],
  "alreadyShredded": true,
  "ledgerForked": true,
  "receipt": {
    "algorithm": "ECDSA_SHA_256"
  }
}

202

In progress: send the same request again until it answers 200.

Media typeapplication/json

The time budget of the call ended. Send the same request again until it answers 200; no entry is written twice.

object

status

required

string

Allowed values: in_progress

ledger

required

string

subjectRef

required

The pseudonym of the subject.

string

/^[0-9a-f]{32}$/

entries

required

The shred entries recorded so far. The final 200 lists them again.

Array<object>

The receipt of an appended entry. Keep receipts: the offline verifier checks them against the archive.

object

key

required

Collection:id

string

id

required

ULID, a hyphen and the two-digit shard. Increases within a shard.

string

shard

required

string

/^[0-9]{2}$/

seq

required

Sequence number of the entry on its shard.

integer

>= 1

at

required

Epoch milliseconds (the ULID time of id).

integer format: int64

hash

required

SHA-256 hex of this entry.

string

/^[0-9a-f]{64}$/

prevHash

required

SHA-256 hex of the previous entry on the shard (the genesis hash for seq 1).

string

/^[0-9a-f]{64}$/

ledger

required

The ledger name.

string

source

Who wrote the entry, set by the KV service from the authenticated caller (never from the body) and covered by the entry hash. platform: a Quant service (quant-ledger writes the shred entries); api: an API caller (an append through this API with a portal token records principal token:); dashboard: a portal user (principal: the portal user id); edge: an edge function (principal //). An API caller with the API secret only records principal api-secret. Absent on entries written before provenance existed.

object

type

required

string

Allowed values: platform api dashboard edge

principal

required

string

<= 256 characters /^[A-Za-z0-9][A-Za-z0-9._:@/-]*$/

replayed

Present only on a retry with the same idempotencyKey: this is the first receipt.

boolean

Example

{
  "status": "in_progress",
  "entries": [
    {
      "key": "ai-use:agency-1:01M5104A000000000000000000-00",
      "id": "01M5104A000000000000000000-00",
      "source": {
        "type": "platform",
        "principal": "token:42"
      },
      "replayed": true
    }
  ]
}

400

Invalid request: VALIDATION, LIMIT_EXCEEDED, CURSOR_INVALID, REQUIRES_FORMAT_2 and the route-specific 400 codes.

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code	status	retryable	meaning
VALIDATION	400	false	The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED	400	false	A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID	400	false	The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2	400	false	The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED	400	false	An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL	400	false	A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE	400	false	A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND	400	false	This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED	400	false	The ledger needs a subject field in each entry.
LEDGER_DIRECTION	400	false	A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED	400	false	confirm is missing or does not equal the store name.
SCOPE_REQUIRED	403	false	The token does not list the scope that the route needs.
PERMISSION_DENIED	403	false	The role of the token user does not have the permission.
FORBIDDEN	403	false	The store is a system store and cannot be purged.
KEY_NOT_FOUND	404	false	The key does not exist or has expired.
STORE_NOT_FOUND	404	false	The store does not exist or is not in this project.
EXPORT_NOT_FOUND	404	false	The store has no export.
LEDGER_NOT_FOUND	404	false	The ledger does not exist.
SUBJECT_NOT_FOUND	404	false	The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND	404	false	The verification run does not exist.
SHRED_NOT_FOUND	404	false	The erasure record does not exist.
INDEX_NOT_FOUND	404	false	The index does not exist.
NOT_FOUND	404	false	No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT	409	false	The upgrade action is not valid in the current upgrade state.
CONFLICT	409	false	A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION	409	false	A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS	409	false	An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY	409	false	The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED	409	false	The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT	409	false	A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED	409	false	The store name is held by a retained ledger archive.
LEDGER_FORKED	409	false	The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED	409	false	The ledger was dropped.
LEDGER_FORMAT_RETIRED	409	false	The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED	409	false	The store still exists. Delete the store first.
ARCHIVE_RETAINED	409	false	The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS	409	false	Another purge of the store is running. See purgeId.
PURGE_BLOCKED	409	false	The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE	409	false	The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED	409	true	The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION	409	true	Another write changed the same data at the same time. Send again.
INDEX_NOT_READY	409	true	The index is still building. Send again later.
LEDGER_NOT_READY	409	true	The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED	429	true	Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL	500	false	The KV service failed. No detail is given.
STORE_MIGRATING	503	true	The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE	503	true (false when the outcome of a write is unknown)	The KV service did not answer. With retryable false, read the data before you send the write again.

object

error

required

Always true.

boolean

message

required

string

code

required

string

Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE

retryable

required

True when the same request can be sent again safely.

boolean

key

CONFLICT: the key the condition named.

string

currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string

reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string

Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead

retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time

activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time

collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string

shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string

operation

Transact: the index of the failing operation.

integer

index

UNIQUE_VIOLATION: the unique index.

string

existingKey

UNIQUE_VIOLATION: the key that holds the value.

string

ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>

object

name

required

The ledger name.

string

state

required

The ledger state (PENDING, ACTIVE or DROPPED).

string

reason

required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string

Allowed values: not_dropped not_drained

hint

What to do next, when the KV service gives a hint.

string

state

The current state of the store, index, ledger or export, when the error names it.

string

Example

{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

403

SCOPE_REQUIRED (the token does not list the scope) or PERMISSION_DENIED (the role does not have the permission).

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code	status	retryable	meaning
VALIDATION	400	false	The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED	400	false	A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID	400	false	The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2	400	false	The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED	400	false	An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL	400	false	A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE	400	false	A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND	400	false	This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED	400	false	The ledger needs a subject field in each entry.
LEDGER_DIRECTION	400	false	A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED	400	false	confirm is missing or does not equal the store name.
SCOPE_REQUIRED	403	false	The token does not list the scope that the route needs.
PERMISSION_DENIED	403	false	The role of the token user does not have the permission.
FORBIDDEN	403	false	The store is a system store and cannot be purged.
KEY_NOT_FOUND	404	false	The key does not exist or has expired.
STORE_NOT_FOUND	404	false	The store does not exist or is not in this project.
EXPORT_NOT_FOUND	404	false	The store has no export.
LEDGER_NOT_FOUND	404	false	The ledger does not exist.
SUBJECT_NOT_FOUND	404	false	The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND	404	false	The verification run does not exist.
SHRED_NOT_FOUND	404	false	The erasure record does not exist.
INDEX_NOT_FOUND	404	false	The index does not exist.
NOT_FOUND	404	false	No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT	409	false	The upgrade action is not valid in the current upgrade state.
CONFLICT	409	false	A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION	409	false	A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS	409	false	An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY	409	false	The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED	409	false	The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT	409	false	A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED	409	false	The store name is held by a retained ledger archive.
LEDGER_FORKED	409	false	The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED	409	false	The ledger was dropped.
LEDGER_FORMAT_RETIRED	409	false	The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED	409	false	The store still exists. Delete the store first.
ARCHIVE_RETAINED	409	false	The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS	409	false	Another purge of the store is running. See purgeId.
PURGE_BLOCKED	409	false	The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE	409	false	The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED	409	true	The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION	409	true	Another write changed the same data at the same time. Send again.
INDEX_NOT_READY	409	true	The index is still building. Send again later.
LEDGER_NOT_READY	409	true	The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED	429	true	Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL	500	false	The KV service failed. No detail is given.
STORE_MIGRATING	503	true	The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE	503	true (false when the outcome of a write is unknown)	The KV service did not answer. With retryable false, read the data before you send the write again.

object

error

required

Always true.

boolean

message

required

string

code

required

string

Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE

retryable

required

True when the same request can be sent again safely.

boolean

key

CONFLICT: the key the condition named.

string

currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string

reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string

Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead

retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time

activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time

collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string

shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string

operation

Transact: the index of the failing operation.

integer

index

UNIQUE_VIOLATION: the unique index.

string

existingKey

UNIQUE_VIOLATION: the key that holds the value.

string

ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>

object

name

required

The ledger name.

string

state

required

The ledger state (PENDING, ACTIVE or DROPPED).

string

reason

required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string

Allowed values: not_dropped not_drained

hint

What to do next, when the KV service gives a hint.

string

state

The current state of the store, index, ledger or export, when the error names it.

string

Example

{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

404

KEY_NOT_FOUND, STORE_NOT_FOUND, LEDGER_NOT_FOUND, SUBJECT_NOT_FOUND, EXPORT_NOT_FOUND, VERIFICATION_NOT_FOUND, SHRED_NOT_FOUND, INDEX_NOT_FOUND or NOT_FOUND (no archive, tombstone or purge).

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code	status	retryable	meaning
VALIDATION	400	false	The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED	400	false	A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID	400	false	The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2	400	false	The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED	400	false	An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL	400	false	A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE	400	false	A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND	400	false	This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED	400	false	The ledger needs a subject field in each entry.
LEDGER_DIRECTION	400	false	A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED	400	false	confirm is missing or does not equal the store name.
SCOPE_REQUIRED	403	false	The token does not list the scope that the route needs.
PERMISSION_DENIED	403	false	The role of the token user does not have the permission.
FORBIDDEN	403	false	The store is a system store and cannot be purged.
KEY_NOT_FOUND	404	false	The key does not exist or has expired.
STORE_NOT_FOUND	404	false	The store does not exist or is not in this project.
EXPORT_NOT_FOUND	404	false	The store has no export.
LEDGER_NOT_FOUND	404	false	The ledger does not exist.
SUBJECT_NOT_FOUND	404	false	The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND	404	false	The verification run does not exist.
SHRED_NOT_FOUND	404	false	The erasure record does not exist.
INDEX_NOT_FOUND	404	false	The index does not exist.
NOT_FOUND	404	false	No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT	409	false	The upgrade action is not valid in the current upgrade state.
CONFLICT	409	false	A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION	409	false	A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS	409	false	An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY	409	false	The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED	409	false	The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT	409	false	A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED	409	false	The store name is held by a retained ledger archive.
LEDGER_FORKED	409	false	The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED	409	false	The ledger was dropped.
LEDGER_FORMAT_RETIRED	409	false	The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED	409	false	The store still exists. Delete the store first.
ARCHIVE_RETAINED	409	false	The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS	409	false	Another purge of the store is running. See purgeId.
PURGE_BLOCKED	409	false	The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE	409	false	The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED	409	true	The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION	409	true	Another write changed the same data at the same time. Send again.
INDEX_NOT_READY	409	true	The index is still building. Send again later.
LEDGER_NOT_READY	409	true	The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED	429	true	Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL	500	false	The KV service failed. No detail is given.
STORE_MIGRATING	503	true	The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE	503	true (false when the outcome of a write is unknown)	The KV service did not answer. With retryable false, read the data before you send the write again.

object

error

required

Always true.

boolean

message

required

string

code

required

string

Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE

retryable

required

True when the same request can be sent again safely.

boolean

key

CONFLICT: the key the condition named.

string

currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string

reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string

Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead

retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time

activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time

collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string

shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string

operation

Transact: the index of the failing operation.

integer

index

UNIQUE_VIOLATION: the unique index.

string

existingKey

UNIQUE_VIOLATION: the key that holds the value.

string

ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>

object

name

required

The ledger name.

string

state

required

The ledger state (PENDING, ACTIVE or DROPPED).

string

reason

required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string

Allowed values: not_dropped not_drained

hint

What to do next, when the KV service gives a hint.

string

state

The current state of the store, index, ledger or export, when the error names it.

string

Example

{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

409

CONFLICT, UNIQUE_VIOLATION, UPGRADE_CONFLICT, EXPORT_IN_PROGRESS, the LEDGER_* conflicts and the archive purge conflicts STORE_NOT_DELETED, ARCHIVE_RETAINED, PURGE_IN_PROGRESS, PURGE_BLOCKED and PURGE_NOT_COMPLETE (not retryable); CONTENTION, INDEX_NOT_READY, LEDGER_NOT_READY and DIGEST_OWED (retryable).

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code	status	retryable	meaning
VALIDATION	400	false	The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED	400	false	A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID	400	false	The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2	400	false	The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED	400	false	An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL	400	false	A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE	400	false	A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND	400	false	This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED	400	false	The ledger needs a subject field in each entry.
LEDGER_DIRECTION	400	false	A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED	400	false	confirm is missing or does not equal the store name.
SCOPE_REQUIRED	403	false	The token does not list the scope that the route needs.
PERMISSION_DENIED	403	false	The role of the token user does not have the permission.
FORBIDDEN	403	false	The store is a system store and cannot be purged.
KEY_NOT_FOUND	404	false	The key does not exist or has expired.
STORE_NOT_FOUND	404	false	The store does not exist or is not in this project.
EXPORT_NOT_FOUND	404	false	The store has no export.
LEDGER_NOT_FOUND	404	false	The ledger does not exist.
SUBJECT_NOT_FOUND	404	false	The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND	404	false	The verification run does not exist.
SHRED_NOT_FOUND	404	false	The erasure record does not exist.
INDEX_NOT_FOUND	404	false	The index does not exist.
NOT_FOUND	404	false	No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT	409	false	The upgrade action is not valid in the current upgrade state.
CONFLICT	409	false	A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION	409	false	A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS	409	false	An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY	409	false	The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED	409	false	The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT	409	false	A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED	409	false	The store name is held by a retained ledger archive.
LEDGER_FORKED	409	false	The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED	409	false	The ledger was dropped.
LEDGER_FORMAT_RETIRED	409	false	The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED	409	false	The store still exists. Delete the store first.
ARCHIVE_RETAINED	409	false	The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS	409	false	Another purge of the store is running. See purgeId.
PURGE_BLOCKED	409	false	The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE	409	false	The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED	409	true	The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION	409	true	Another write changed the same data at the same time. Send again.
INDEX_NOT_READY	409	true	The index is still building. Send again later.
LEDGER_NOT_READY	409	true	The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED	429	true	Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL	500	false	The KV service failed. No detail is given.
STORE_MIGRATING	503	true	The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE	503	true (false when the outcome of a write is unknown)	The KV service did not answer. With retryable false, read the data before you send the write again.

object

error

required

Always true.

boolean

message

required

string

code

required

string

Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE

retryable

required

True when the same request can be sent again safely.

boolean

key

CONFLICT: the key the condition named.

string

currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string

reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string

Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead

retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time

activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time

collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string

shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string

operation

Transact: the index of the failing operation.

integer

index

UNIQUE_VIOLATION: the unique index.

string

existingKey

UNIQUE_VIOLATION: the key that holds the value.

string

ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>

object

name

required

The ledger name.

string

state

required

The ledger state (PENDING, ACTIVE or DROPPED).

string

reason

required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string

Allowed values: not_dropped not_drained

hint

What to do next, when the KV service gives a hint.

string

state

The current state of the store, index, ledger or export, when the error names it.

string

Example

{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

429

RATE_LIMITED (retryable): a rate limit is used up. The limits are the per-token limit (api-token, default 240 requests per minute per token and organisation) and, on some operations, the per-project KV limits (kv-admin 10, kv-erase 30, kv-verify 6 requests per minute). Wait for Retry-After seconds, then send the request again. See Rate limits in the API description.

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code	status	retryable	meaning
VALIDATION	400	false	The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED	400	false	A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID	400	false	The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2	400	false	The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED	400	false	An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL	400	false	A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE	400	false	A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND	400	false	This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED	400	false	The ledger needs a subject field in each entry.
LEDGER_DIRECTION	400	false	A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED	400	false	confirm is missing or does not equal the store name.
SCOPE_REQUIRED	403	false	The token does not list the scope that the route needs.
PERMISSION_DENIED	403	false	The role of the token user does not have the permission.
FORBIDDEN	403	false	The store is a system store and cannot be purged.
KEY_NOT_FOUND	404	false	The key does not exist or has expired.
STORE_NOT_FOUND	404	false	The store does not exist or is not in this project.
EXPORT_NOT_FOUND	404	false	The store has no export.
LEDGER_NOT_FOUND	404	false	The ledger does not exist.
SUBJECT_NOT_FOUND	404	false	The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND	404	false	The verification run does not exist.
SHRED_NOT_FOUND	404	false	The erasure record does not exist.
INDEX_NOT_FOUND	404	false	The index does not exist.
NOT_FOUND	404	false	No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT	409	false	The upgrade action is not valid in the current upgrade state.
CONFLICT	409	false	A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION	409	false	A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS	409	false	An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY	409	false	The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED	409	false	The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT	409	false	A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED	409	false	The store name is held by a retained ledger archive.
LEDGER_FORKED	409	false	The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED	409	false	The ledger was dropped.
LEDGER_FORMAT_RETIRED	409	false	The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED	409	false	The store still exists. Delete the store first.
ARCHIVE_RETAINED	409	false	The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS	409	false	Another purge of the store is running. See purgeId.
PURGE_BLOCKED	409	false	The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE	409	false	The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED	409	true	The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION	409	true	Another write changed the same data at the same time. Send again.
INDEX_NOT_READY	409	true	The index is still building. Send again later.
LEDGER_NOT_READY	409	true	The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED	429	true	Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL	500	false	The KV service failed. No detail is given.
STORE_MIGRATING	503	true	The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE	503	true (false when the outcome of a write is unknown)	The KV service did not answer. With retryable false, read the data before you send the write again.

object

error

required

Always true.

boolean

message

required

string

code

required

string

Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE

retryable

required

True when the same request can be sent again safely.

boolean

key

CONFLICT: the key the condition named.

string

currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string

reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string

Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead

retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time

activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time

collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string

shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string

operation

Transact: the index of the failing operation.

integer

index

UNIQUE_VIOLATION: the unique index.

string

existingKey

UNIQUE_VIOLATION: the key that holds the value.

string

ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>

object

name

required

The ledger name.

string

state

required

The ledger state (PENDING, ACTIVE or DROPPED).

string

reason

required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string

Allowed values: not_dropped not_drained

hint

What to do next, when the KV service gives a hint.

string

state

The current state of the store, index, ledger or export, when the error names it.

string

Example

{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

Headers

Retry-After

integer

Seconds to wait before the next request.

RateLimit-Limit

integer

>= 1

The request limit of the window (IETF draft). X-RateLimit-Limit carries the same value.

RateLimit-Remaining

integer

Requests left in the window: 0 on a 429 (IETF draft). X-RateLimit-Remaining carries the same value.

RateLimit-Reset

integer

Seconds until the window resets (IETF draft). X-RateLimit-Reset is the same moment as a Unix timestamp.

500

INTERNAL: the KV service failed. No detail is given.

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code	status	retryable	meaning
VALIDATION	400	false	The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED	400	false	A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID	400	false	The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2	400	false	The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED	400	false	An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL	400	false	A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE	400	false	A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND	400	false	This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED	400	false	The ledger needs a subject field in each entry.
LEDGER_DIRECTION	400	false	A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED	400	false	confirm is missing or does not equal the store name.
SCOPE_REQUIRED	403	false	The token does not list the scope that the route needs.
PERMISSION_DENIED	403	false	The role of the token user does not have the permission.
FORBIDDEN	403	false	The store is a system store and cannot be purged.
KEY_NOT_FOUND	404	false	The key does not exist or has expired.
STORE_NOT_FOUND	404	false	The store does not exist or is not in this project.
EXPORT_NOT_FOUND	404	false	The store has no export.
LEDGER_NOT_FOUND	404	false	The ledger does not exist.
SUBJECT_NOT_FOUND	404	false	The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND	404	false	The verification run does not exist.
SHRED_NOT_FOUND	404	false	The erasure record does not exist.
INDEX_NOT_FOUND	404	false	The index does not exist.
NOT_FOUND	404	false	No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT	409	false	The upgrade action is not valid in the current upgrade state.
CONFLICT	409	false	A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION	409	false	A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS	409	false	An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY	409	false	The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED	409	false	The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT	409	false	A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED	409	false	The store name is held by a retained ledger archive.
LEDGER_FORKED	409	false	The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED	409	false	The ledger was dropped.
LEDGER_FORMAT_RETIRED	409	false	The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED	409	false	The store still exists. Delete the store first.
ARCHIVE_RETAINED	409	false	The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS	409	false	Another purge of the store is running. See purgeId.
PURGE_BLOCKED	409	false	The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE	409	false	The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED	409	true	The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION	409	true	Another write changed the same data at the same time. Send again.
INDEX_NOT_READY	409	true	The index is still building. Send again later.
LEDGER_NOT_READY	409	true	The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED	429	true	Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL	500	false	The KV service failed. No detail is given.
STORE_MIGRATING	503	true	The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE	503	true (false when the outcome of a write is unknown)	The KV service did not answer. With retryable false, read the data before you send the write again.

object

error

required

Always true.

boolean

message

required

string

code

required

string

Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE

retryable

required

True when the same request can be sent again safely.

boolean

key

CONFLICT: the key the condition named.

string

currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string

reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string

Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead

retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time

activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time

collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string

shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string

operation

Transact: the index of the failing operation.

integer

index

UNIQUE_VIOLATION: the unique index.

string

existingKey

UNIQUE_VIOLATION: the key that holds the value.

string

ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>

object

name

required

The ledger name.

string

state

required

The ledger state (PENDING, ACTIVE or DROPPED).

string

reason

required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string

Allowed values: not_dropped not_drained

hint

What to do next, when the KV service gives a hint.

string

state

The current state of the store, index, ledger or export, when the error names it.

string

Example

{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

503

STORE_MIGRATING (retryable, Retry-After) or UNAVAILABLE. UNAVAILABLE with retryable true (for example a new store whose table is still being created, with Retry-After 5) is safe to retry with backoff; honour Retry-After. With retryable false the outcome of a write is unknown: read before you write again.

Media typeapplication/json

Error body of every KV v2 route. A superset of V2Error. HTTP 400, 404, 409, 429 and 503 keep the KV service status, code and retryable. A KV service failure that the caller cannot act on is 500 INTERNAL. When retryable is true, the same request can be sent again (after Retry-After when present).

code	status	retryable	meaning
VALIDATION	400	false	The request is not valid (body, parameter, key or value).
LIMIT_EXCEEDED	400	false	A size or count limit is exceeded (item over 400 KB, batch, transact, value).
CURSOR_INVALID	400	false	The cursor is not valid for this request. Start the list again.
REQUIRES_FORMAT_2	400	false	The operation needs a format 2 store. Upgrade the store first.
INDEX_FIELD_ENCRYPTED	400	false	An indexed field is in a secret (encrypted) value.
COUNT_WITH_TTL	400	false	A count index cannot include items that have a ttl.
LEDGER_IMMUTABLE	400	false	A ledger entry cannot be changed or deleted. Use append.
LEDGER_INDEX_KIND	400	false	This index kind is not allowed on a ledger collection.
LEDGER_SUBJECT_REQUIRED	400	false	The ledger needs a subject field in each entry.
LEDGER_DIRECTION	400	false	A ledger setting can only be raised, not lowered.
CONFIRMATION_REQUIRED	400	false	confirm is missing or does not equal the store name.
SCOPE_REQUIRED	403	false	The token does not list the scope that the route needs.
PERMISSION_DENIED	403	false	The role of the token user does not have the permission.
FORBIDDEN	403	false	The store is a system store and cannot be purged.
KEY_NOT_FOUND	404	false	The key does not exist or has expired.
STORE_NOT_FOUND	404	false	The store does not exist or is not in this project.
EXPORT_NOT_FOUND	404	false	The store has no export.
LEDGER_NOT_FOUND	404	false	The ledger does not exist.
SUBJECT_NOT_FOUND	404	false	The ledger has no entries for the subject.
VERIFICATION_NOT_FOUND	404	false	The verification run does not exist.
SHRED_NOT_FOUND	404	false	The erasure record does not exist.
INDEX_NOT_FOUND	404	false	The index does not exist.
NOT_FOUND	404	false	No archive, tombstone or purge exists for the store or purge id.
UPGRADE_CONFLICT	409	false	The upgrade action is not valid in the current upgrade state.
CONFLICT	409	false	A condition (ifAbsent, ifVersion, check) failed. See reason, key and currentVersion.
UNIQUE_VIOLATION	409	false	A unique index already has the value. See index and existingKey.
EXPORT_IN_PROGRESS	409	false	An export of the store is already running.
LEDGER_COLLECTION_NOT_EMPTY	409	false	The collection already has items, so it cannot become a ledger.
LEDGER_RETAINED	409	false	The ledger is in its retention period. See retainUntil.
LEDGER_PRESENT	409	false	A ledger blocks the action. See ledgers.
STORE_NAME_RETAINED	409	false	The store name is held by a retained ledger archive.
LEDGER_FORKED	409	false	The ledger chain does not agree with its archive or digest. See reason.
LEDGER_DROPPED	409	false	The ledger was dropped.
LEDGER_FORMAT_RETIRED	409	false	The ledger uses a retired subject format. Declare a new ledger.
STORE_NOT_DELETED	409	false	The store still exists. Delete the store first.
ARCHIVE_RETAINED	409	false	The archive is still locked or in its 24-hour quiet period. See retainedUntil.
PURGE_IN_PROGRESS	409	false	Another purge of the store is running. See purgeId.
PURGE_BLOCKED	409	false	The last purge is blocked and needs Quant support. See purgeId.
PURGE_NOT_COMPLETE	409	false	The purge is not complete, so there is no receipt yet. See state.
DIGEST_OWED	409	true	The last ledger entries are not in a signed digest yet. Send the delete again in a few minutes.
CONTENTION	409	true	Another write changed the same data at the same time. Send again.
INDEX_NOT_READY	409	true	The index is still building. Send again later.
LEDGER_NOT_READY	409	true	The ledger is PENDING. Send again after activeAfter.
RATE_LIMITED	429	true	Too many requests. Wait for Retry-After seconds. Also retryAfter (seconds) on a purge start.
INTERNAL	500	false	The KV service failed. No detail is given.
STORE_MIGRATING	503	true	The store is being upgraded. Wait for Retry-After seconds.
UNAVAILABLE	503	true (false when the outcome of a write is unknown)	The KV service did not answer. With retryable false, read the data before you send the write again.

object

error

required

Always true.

boolean

message

required

string

code

required

string

Allowed values: VALIDATION LIMIT_EXCEEDED CURSOR_INVALID REQUIRES_FORMAT_2 INDEX_FIELD_ENCRYPTED COUNT_WITH_TTL LEDGER_IMMUTABLE LEDGER_INDEX_KIND LEDGER_SUBJECT_REQUIRED LEDGER_DIRECTION CONFIRMATION_REQUIRED SCOPE_REQUIRED PERMISSION_DENIED FORBIDDEN KEY_NOT_FOUND STORE_NOT_FOUND EXPORT_NOT_FOUND LEDGER_NOT_FOUND SUBJECT_NOT_FOUND VERIFICATION_NOT_FOUND SHRED_NOT_FOUND INDEX_NOT_FOUND NOT_FOUND UPGRADE_CONFLICT CONFLICT UNIQUE_VIOLATION EXPORT_IN_PROGRESS LEDGER_COLLECTION_NOT_EMPTY LEDGER_RETAINED LEDGER_PRESENT STORE_NAME_RETAINED LEDGER_FORKED LEDGER_DROPPED LEDGER_FORMAT_RETIRED STORE_NOT_DELETED ARCHIVE_RETAINED PURGE_IN_PROGRESS PURGE_BLOCKED PURGE_NOT_COMPLETE DIGEST_OWED CONTENTION INDEX_NOT_READY LEDGER_NOT_READY RATE_LIMITED INTERNAL STORE_MIGRATING UNAVAILABLE

retryable

required

True when the same request can be sent again safely.

boolean

key

CONFLICT: the key the condition named.

string

currentVersion

CONFLICT: the current version, when the key exists and has not expired.

string

reason

CONFLICT: why the condition failed. LEDGER_COLLECTION_NOT_EMPTY, LEDGER_RETAINED, LEDGER_FORKED: the cause.

string

Allowed values: exists version missing expired not_numeric range not_empty check_incomplete unarchived retention_unknown table_replaced archive_ahead digest_ahead

retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time

activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time

collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string

shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string

operation

Transact: the index of the failing operation.

integer

index

UNIQUE_VIOLATION: the unique index.

string

existingKey

UNIQUE_VIOLATION: the key that holds the value.

string

ledgers

LEDGER_PRESENT (store delete): the ledgers that block the delete.

Array<object>

object

name

required

The ledger name.

string

state

required

The ledger state (PENDING, ACTIVE or DROPPED).

string

reason

required

Not_dropped: drop the ledger first (after its retention ends). not_drained: the ledger is DROPPED but its last entries are not archived yet.

string

Allowed values: not_dropped not_drained

hint

What to do next, when the KV service gives a hint.

string

state

The current state of the store, index, ledger or export, when the error names it.

string

Example

{
  "error": true,
  "message": "The condition failed",
  "code": "CONFLICT",
  "retryable": false,
  "key": "user:1",
  "reason": "version",
  "currentVersion": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

Headers

Retry-After

integer