Get the chains, archive lag, digest, anchor and verify state of a ledger

GET

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

curl --request GET \
  --url https://dashboard.quantcdn.io/api/v2/organizations/test-org/projects/test-project/kv/test-org-test-project-orders/ledgers/aiUse/status \
  --header 'Authorization: Bearer <token>'

• QuantCDN Public Cloud
• QuantGov Cloud

The ledger, its chain instances (one per collection and shard that holds entries; 50 per page) with head and archived sequence and archive lag, the retention end, the last digest time, the anchor state, lastVerify, verifyProgress and forked. Pass next_cursor as cursor for the next page of instances.

Authorizations

• BearerAuth
  kv:ledger:read

Parameters

Path Parameters

organization

required

string

Organization identifier

Example

test-org

project

required

string

Project identifier

Example

test-project

store_id

required

string

KV store id, as returned by KV_list

Example

test-org-test-project-orders

ledger_name

required

string

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

Example

aiUse

Query Parameters

cursor

string

The next_cursor of the previous page.

Responses

200

One page of instances.

Media typeapplication/json

The chain instances (50 per page), archive lag, digest, anchor and verify state of a ledger.

object

ledger

required

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

instances

required

Array<object>

One chain: a collection and shard that holds entries.

object

collection

required

string

shard

required

string

/^\d{2}$/

headSeq

required

Sequence number of the last entry.

integer

headAt

Epoch ms of the last entry.

integer format: int64

archivedSeq

required

Last sequence number in the archive.

integer

archiveLagSeconds

required

Age of the oldest unarchived entry; 0 when up to date.

integer

broken

Set when the archive worker found a chain fault (seq, reason, at).

object

key

additional properties

any

lastDigestAt

string format: date-time

retainUntil

string format: date-time

modeRefused

integer

digestModeRefused

integer

modeRetryAfter

string format: date-time

anchor

required

object

type

required

string

Allowed values: none customer-bucket rfc3161

lastDay

string

/^\d{8}$/

failingSince

string format: date-time

error

string

bucketPolicy

Customer-bucket only: the bucket policy (JSON) that lets Quant write the witness copies.

string

lastVerify

The last verify result of the ledger (the daily scheduled full verify, or the last complete API or dashboard verify). ok is true only when complete is true and no shard failed.

object

id

The verification record; KV_ledgers_verifications_report returns it signed.

string

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

at

required

string format: date-time

startedAt

required

string format: date-time

durationMs

integer

ok

required

boolean

entries

required

integer

shardsFailed

required

integer

complete

required

boolean

pages

integer

trigger

required

string

Allowed values: scheduled api dashboard

scope

required

The request range; empty for a full verify.

object

collection

string

since

string format: date-time

until

string format: date-time

firstFailure

object

collection

required

string

shard

required

string

seq

integer

reason

required

string

verifyProgress

Present while a scheduled verify runs or is paused between daily runs.

object

key

additional properties

any

forked

Present when the store table no longer matches its archive; appends are refused with LEDGER_FORKED.

object

key

additional properties

any

next_cursor

required

Pass as cursor for the next page of instances; null on the last page.

string

nullable

Example

{
  "ledger": {
    "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"
  },
  "anchor": {
    "type": "none"
  },
  "lastVerify": {
    "trigger": "scheduled",
    "firstFailure": {
      "reason": "hash_mismatch"
    }
  }
}

400

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

Media typeapplication/json

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

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

object

error

required

Always true.

boolean

message

required

string

code

required

string

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

retryable

required

True when the same request can be sent again safely.

boolean

key

CONFLICT: the key the condition named.

string

currentVersion

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

string

reason

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

string

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

retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time

activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time

collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string

shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string

operation

Transact: the index of the failing operation.

integer

index

UNIQUE_VIOLATION: the unique index.

string

existingKey

UNIQUE_VIOLATION: the key that holds the value.

string

ledgers

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

Array<object>

object

name

required

The ledger name.

string

state

required

The ledger state (PENDING, ACTIVE or DROPPED).

string

reason

required

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

string

Allowed values: not_dropped not_drained

hint

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

string

state

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

string

Example

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

403

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

Media typeapplication/json

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

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

object

error

required

Always true.

boolean

message

required

string

code

required

string

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

retryable

required

True when the same request can be sent again safely.

boolean

key

CONFLICT: the key the condition named.

string

currentVersion

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

string

reason

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

string

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

retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time

activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time

collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string

shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string

operation

Transact: the index of the failing operation.

integer

index

UNIQUE_VIOLATION: the unique index.

string

existingKey

UNIQUE_VIOLATION: the key that holds the value.

string

ledgers

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

Array<object>

object

name

required

The ledger name.

string

state

required

The ledger state (PENDING, ACTIVE or DROPPED).

string

reason

required

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

string

Allowed values: not_dropped not_drained

hint

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

string

state

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

string

Example

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

404

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

Media typeapplication/json

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

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

object

error

required

Always true.

boolean

message

required

string

code

required

string

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

retryable

required

True when the same request can be sent again safely.

boolean

key

CONFLICT: the key the condition named.

string

currentVersion

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

string

reason

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

string

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

retainUntil

LEDGER_RETAINED: when the archive retention ends.

string format: date-time

activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time

collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string

shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string

operation

Transact: the index of the failing operation.

integer

index

UNIQUE_VIOLATION: the unique index.

string

existingKey

UNIQUE_VIOLATION: the key that holds the value.

string

ledgers

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

Array<object>

object

name

required

The ledger name.

string

state

required

The ledger state (PENDING, ACTIVE or DROPPED).

string

reason

required

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

string

Allowed values: not_dropped not_drained

hint

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

string

state

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

string

Example

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

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