Skip to content
QuantCDN

Dry run or start a purge of a retained archive

POST
/api/v2/organizations/{organization}/kv/archives/{store_name}/purge
curl --request POST \
  --url https://dashboard.quantcdn.io/api/v2/organizations/test-org/kv/archives/orders/purge \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "dryRun": false, "confirm": "orders", "reason": "Handoff accepted 2026-10-01" }'

Starts the purge of the retained ledger archive of a deleted store, or reports what it would delete. dryRun defaults to true: a dry run answers 200 with dryRun true and the counts, and deletes nothing. Send dryRun false to start: the answer is 202 with purgeId and state. Both answers use the schema V2KvArchivePurgeAnswer. confirm must equal the store name, also for a dry run. Quant sets requestedBy; a client value is refused (400 VALIDATION). A repeat with the same Idempotency-Key answers 202 with the existing purge. Nothing is deleted until every object is past its lock: a purge that finds a lock or the quiet period ends as RETAINED, and a new start within 1 hour of a RETAINED result is 429 RATE_LIMITED. System stores cannot be purged (403 FORBIDDEN; the check ignores case). Read the purge with KV_archives_purge_show, then the receipt and the manifest. The route is scoped to the organisation because a deleted store has no project link; the token also needs projects:read. This route needs both explicit scopes, kv:ledger:admin and kv:ledger:purge (full_access and tokens without a scope list cannot use it), the ledger_admin permission, and, in the dashboard, a step-up (authenticator code or password). A purge cannot be undone. Rate limit: 10 requests per minute per organisation. Audited (store and purge id only, never the reason). The receipt is the platform’s signed statement, not a proof of absence. A token restricted to projects is refused (403 PERMISSION_DENIED): use a token without a project restriction.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
organization
required
string

Organization identifier

Example
test-org
store_name
required
string
/^[A-Za-z0-9_-]{1,255}$/

The id of the deleted store, as KV_list showed it before the delete

Example
orders

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
/^[A-Za-z0-9._:-]{1,128}$/

1 to 128 characters of letters, digits and . _ : -. A repeat with the same key answers 202 with the existing purge.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

DryRun defaults to true. confirm must equal the store name, also for a dry run (else 400 CONFIRMATION_REQUIRED). requestedBy is set by Quant: a body that has the key requestedBy is 400 VALIDATION. An unknown field is 400 VALIDATION.

object
dryRun

True: report only. false: start the purge.

boolean
default: true
confirm
required

The store name, exactly.

string
reason

Optional note kept with the purge and the receipt. No control characters. It is never echoed in an error message.

string
nullable >= 1 characters <= 500 characters
Example
{
  "dryRun": false,
  "confirm": "orders",
  "reason": "Handoff accepted 2026-10-01"
}

Responses

Section titled “Responses”

200

Section titled “200”

Dry run: what a purge would delete (dryRun true and the counts).

Media typeapplication/json

The one answer of KV_archives_purge, for 200 and 202; no property is required. A dry run answers 200 with dryRun true and the counts (nothing is deleted). A start answers 202 with purgeId and state (the purge was accepted, or a repeat with the same Idempotency-Key found the existing one); read it with KV_archives_purge_show. For a dry run, eligible is false when any version is locked, a legal hold is on, a delete marker exists, or the quiet period (24 hours after deletedAt) has not passed. At most 100,000 versions are counted inline (partial true past that).

object
purgeId

Set on a start (202).

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

Set on a start (202).

string
Allowed values: GATING PLANNING DELETING VERIFYING SIGNING COMPLETE RETAINED BLOCKED CANCELLED
dryRun
boolean
store
string
eligible
boolean
partial
boolean
versions
integer
bytes
integer
ledgerObjects
integer
digestObjects
integer
anchorObjects
integer
deleteMarkers
integer
latestRetainUntil
string format: date-time
nullable
earliestPurgeAt
string format: date-time
nullable
quietUntil
string format: date-time
nullable
Example
{
  "state": "GATING",
  "dryRun": true
}

202

Section titled “202”

The purge was accepted, or a repeat with the same Idempotency-Key found the existing one (purgeId and state).

Media typeapplication/json

The one answer of KV_archives_purge, for 200 and 202; no property is required. A dry run answers 200 with dryRun true and the counts (nothing is deleted). A start answers 202 with purgeId and state (the purge was accepted, or a repeat with the same Idempotency-Key found the existing one); read it with KV_archives_purge_show. For a dry run, eligible is false when any version is locked, a legal hold is on, a delete marker exists, or the quiet period (24 hours after deletedAt) has not passed. At most 100,000 versions are counted inline (partial true past that).

object
purgeId

Set on a start (202).

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

Set on a start (202).

string
Allowed values: GATING PLANNING DELETING VERIFYING SIGNING COMPLETE RETAINED BLOCKED CANCELLED
dryRun
boolean
store
string
eligible
boolean
partial
boolean
versions
integer
bytes
integer
ledgerObjects
integer
digestObjects
integer
anchorObjects
integer
deleteMarkers
integer
latestRetainUntil
string format: date-time
nullable
earliestPurgeAt
string format: date-time
nullable
quietUntil
string format: date-time
nullable
Example
{
  "state": "GATING",
  "dryRun": true
}

400

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Headers”
Retry-After
integer