Declare a ledger

POST

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

curl --request POST \
  --url https://dashboard.quantcdn.io/api/v2/organizations/test-org/projects/test-project/kv/test-org-test-project-orders/ledgers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "aiUse", "collection": "ai-use:*", "chains": 4, "retentionDays": 2555, "lockMode": "governance", "personalFields": [ "requesterName" ], "subjectField": "requesterId", "subjectMode": "pseudonym", "subjectCase": "fold", "anchor": { "type": "rfc3161", "tsaUrl": "http://timestamp.digicert.com" } }'

• QuantCDN Public Cloud
• QuantGov Cloud

Declares an append-only, hash-chained ledger on a collection (or a pattern where * is one whole segment) of a format 2 store. The collection must be empty: no keys and no ledger entries. The ledger is PENDING for 75 seconds (appends answer 409 LEDGER_NOT_READY until activeAfter); then the emptiness check runs again and the ledger becomes ACTIVE, or FAILED when a key was written in that window. Declaring the name of a FAILED ledger replaces it. The answer is 202 with the ledger (state PENDING): the KV service accepts the declaration and finishes it after the wait. A store has at most 20 ledgers (400 LIMIT_EXCEEDED). LEDGER_SUBJECT_REQUIRED has a fixed message. name, collection, personalFields, subjectField, subjectMode, subjectCase, anchor and writerPolicy can never change; chains, retentionDays and lockMode can only go up (KV_ledgers_update). A ledger cannot be dropped before its archive retention ends.\n\nNeeds a token with the explicit kv:ledger:admin scope (full_access and tokens without a scope list cannot use it) and the ledger_admin permission. Rate limit: 10 requests per minute per project, shared by every kv-admin operation (index create, delete and resume; upgrade; export create and resume; ledger declare, raise and drop). Over the limit the answer is 429 RATE_LIMITED with a Retry-After header: clients (for example Terraform) must wait Retry-After seconds, then send the request again. Audited (the definition fields and definitionHash, never a value). A lost connection is 503 UNAVAILABLE with retryable false: read the ledger (KV_ledgers_show) before you send it again.

Authorizations

• BearerAuth
  kv:ledger:admin

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

Request Body^required

Media typeapplication/json

A ledger definition. The collection must be empty (no keys, no ledger entries). name, collection, personalFields, subjectField, subjectMode, subjectCase, anchor and writerPolicy can never change. chains, retentionDays and lockMode can only go up (KV_ledgers_update). An unknown field is 400 VALIDATION.

object

name

required

Unique in the store.

string

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

collection

required

A collection name, or a pattern where * as a whole segment matches exactly one segment. Must not overlap another ledger. At most 512 UTF-8 bytes; every concrete collection appended to the ledger is at most 512 bytes too.

string

>= 1 characters <= 512 characters

chains

required

Parallel hash chains (shards) per collection.

integer

>= 1 <= 64

retentionDays

required

S3 Object Lock retention of the archive, in days. The ledger cannot be dropped before it ends.

integer

>= 1 <= 36500

lockMode

required

S3 Object Lock mode of the archive. governance can become compliance later, never back.

string

Allowed values: governance compliance

personalFields

Top-level value fields that are encrypted per data subject, so a shred (KV_ledgers_shred) can erase them. Needs subjectField (else 400 LEDGER_SUBJECT_REQUIRED). Any field name except at. An index cannot use a personal field (400 INDEX_FIELD_ENCRYPTED).

Array<string>

<= 20 items unique items

subjectField

The top-level value field that names the data subject. It is not a personal field. May be set without personal fields; such a ledger is pseudonymised and can be shredded. $subject and $subjectTag are reserved value field names.

string

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

subjectMode

How the subject field is stored. pseudonym (the default): a random token, and after a shred nobody can link the remaining entries to the person. clear: the value as written; after a shred the id and the activity stay. Needs subjectField. Cannot change.

string

Allowed values: pseudonym clear

subjectCase

Exact (the default): ids that differ in case are different subjects. fold: case is ignored; use it for email addresses and usernames. Needs subjectField. Cannot change.

string

Allowed values: exact fold

anchor

External witness of the daily digests. Default type none. customer-bucket writes each digest to your S3 bucket (needs bucketArn and accountId); rfc3161 gets a timestamp token from tsaUrl.

object

type

required

string

Allowed values: none customer-bucket rfc3161

bucketArn

Customer-bucket only (required on declare).

string

/^arn:aws:s3:::[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/

prefix

Customer-bucket only, optional. Anchor keys are //….

string

"" <= 256 characters /^[A-Za-z0-9!_.*'()/-]{0,256}$/

accountId

Customer-bucket only (required on declare): the AWS account that owns the bucket. Every anchor write sends it as ExpectedBucketOwner.

string

/^\d{12}$/

tsaUrl

Rfc3161 only.

string

Allowed values: http://timestamp.digicert.com

Example

{
  "type": "customer-bucket",
  "bucketArn": "arn:aws:s3:::example-ledger-anchors",
  "prefix": "kv/",
  "accountId": "123456789012"
}

writerPolicy

Immutable allowlist of internal Quant platform writers, included in definitionHash. With a writer policy, appends through the API are refused (only the listed platform services can write). Without it, appends work as usual. A ledger with personalFields must list quant-ledger, which writes the shred entries. This is not a read or management access policy.

object

platformPrincipals

required

The platform service principals that may append (1 to 16, unique).

Array<string>

>= 1 items <= 16 items unique items

Example

[
  "quant-ai-governance",
  "quant-ledger"
]

Example

{
  "name": "aiUse",
  "collection": "ai-use:*",
  "chains": 4,
  "retentionDays": 2555,
  "lockMode": "governance",
  "personalFields": [
    "requesterName"
  ],
  "subjectField": "requesterId",
  "subjectMode": "pseudonym",
  "subjectCase": "fold",
  "anchor": {
    "type": "rfc3161",
    "tsaUrl": "http://timestamp.digicert.com"
  }
}

Responses

202

Accepted: the ledger is declared and PENDING until activeAfter, then ACTIVE (or FAILED). Read it with KV_ledgers_show.

Media typeapplication/json

A ledger definition and its state.

object

name

required

string

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

collection

required

A collection, or a pattern where * is one whole segment.

string

chains

required

integer

>= 1 <= 64

retentionDays

required

integer

>= 1 <= 36500

lockMode

required

string

Allowed values: governance compliance

personalFields

required

Array<string>

subjectField

string

subjectMode

Present when subjectField is set.

string

Allowed values: pseudonym clear

subjectCase

Present when subjectField is set.

string

Allowed values: exact fold

anchor

required

External witness of the daily digests. Default type none. customer-bucket writes each digest to your S3 bucket (needs bucketArn and accountId); rfc3161 gets a timestamp token from tsaUrl.

object

type

required

string

Allowed values: none customer-bucket rfc3161

bucketArn

Customer-bucket only (required on declare).

string

/^arn:aws:s3:::[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/

prefix

Customer-bucket only, optional. Anchor keys are //….

string

"" <= 256 characters /^[A-Za-z0-9!_.*'()/-]{0,256}$/

accountId

Customer-bucket only (required on declare): the AWS account that owns the bucket. Every anchor write sends it as ExpectedBucketOwner.

string

/^\d{12}$/

tsaUrl

Rfc3161 only.

string

Allowed values: http://timestamp.digicert.com

writerPolicy

Immutable allowlist of internal Quant platform writers, included in definitionHash. With a writer policy, appends through the API are refused (only the listed platform services can write). Without it, appends work as usual. A ledger with personalFields must list quant-ledger, which writes the shred entries. This is not a read or management access policy.

object

platformPrincipals

required

The platform service principals that may append (1 to 16, unique).

Array<string>

>= 1 items <= 16 items unique items

state

required

PENDING for 75 seconds after a declare, then ACTIVE or FAILED. DROPPED after KV_ledgers_delete.

string

Allowed values: PENDING ACTIVE FAILED DROPPED

createdAt

required

string format: date-time

activeAfter

required

When a PENDING ledger is checked again and becomes ACTIVE or FAILED.

string format: date-time

definitionHash

required

Hex SHA-256 of the canonical (RFC 8785) definition.

string

updatedAt

string format: date-time

error

FAILED only: why the ledger failed.

string

droppedAt

string format: date-time

Example

{
  "name": "aiUse",
  "collection": "ai-use:*",
  "chains": 4,
  "retentionDays": 2555,
  "lockMode": "governance",
  "personalFields": [
    "requesterName"
  ],
  "subjectField": "requesterId",
  "anchor": {
    "type": "none"
  },
  "state": "PENDING",
  "createdAt": "2026-10-16T00:00:00.000Z",
  "activeAfter": "2026-10-16T00:01:15.000Z",
  "definitionHash": "c4a5e0f1d2b3a4958671e2d3c4b5a6978e9f0a1b2c3d4e5f60718293a4b5c6d7"
}

Headers

X-Quant-KV-Format

string

The store format.

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

STORE_NOT_FOUND: the store does not exist or is not in this project.

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