Skip to content
QuantCDN

List retained ledger archives

GET
/api/v2/organizations/{organization}/kv/archives
curl --request GET \
  --url 'https://dashboard.quantcdn.io/api/v2/organizations/test-org/kv/archives?limit=50' \
  --header 'Authorization: Bearer <token>'

Lists the deleted stores of the organisation that still hold archive objects, as the KV page envelope (data, next_cursor, has_more, page_end). The route is scoped to the organisation because a deleted store has no project link; the token also needs projects:read. Needs 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. A token restricted to projects is refused (403 PERMISSION_DENIED): use a token without a project restriction.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
organization
required
string

Organization identifier

Example
test-org

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 50 >= 1 <= 100

The maximum number of archives in the page (1-100, default 50).

cursor
string

The next_cursor of the previous page.

Responses

Section titled “Responses”

200

Section titled “200”

A page of archives.

Media typeapplication/json

A page of deleted stores that still hold archive objects (the KV page envelope).

object
data
required
Array<object>

The archive of one deleted store.

object
store
string
status

Purged: the latest purge is COMPLETE. purging: a purge is not final. blocked: the latest purge is BLOCKED. retained: a lock or the quiet period is in the future. eligible: otherwise.

string
Allowed values: retained eligible purging blocked purged
deletedAt
string format: date-time
nullable
earliestPurgeAt
string format: date-time
nullable
retainedUntil
string format: date-time
nullable
source
string
Allowed values: tombstone archive
project
string
nullable
purge
object
purgeId

OpenAPI schemas and path parameters for the retained ledger archive routes of deleted stores (A5). Shapes follow the backend contract C-1 (ArchiveStatus, DryRun, Purge, PurgeReceipt, manifest). The list uses the KV page envelope (data, next_cursor, has_more, page_end).

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

COMPLETE, RETAINED, BLOCKED and CANCELLED are final. RETAINED: a lock or the quiet period was found at the gate, nothing was deleted. BLOCKED: needs an operator.

string
Allowed values: GATING PLANNING DELETING VERIFYING SIGNING COMPLETE RETAINED BLOCKED CANCELLED
requestedBy
string
requestedAt
string format: date-time
reason
string
nullable
updatedAt
string format: date-time
completedAt
string format: date-time
nullable
retainedUntil

On a RETAINED purge, the latest lock found.

string format: date-time
nullable
counts
object
versions
integer
bytes
integer
deleted
integer
manifestPages
integer
lastError
object
code
string
message
string
next_cursor
required

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

string
nullable
has_more
required
boolean
page_end
required

Why the page ended: end (no more items), limit (the page has limit items), bytes (the 4,000,000 byte page budget), budget (the read budget of one request). With bytes or budget a page can have fewer than limit items while has_more is true. Null when the KV service does not report it.

string
nullable
Allowed values: end limit bytes budget
Example
{
  "data": [
    {
      "status": "retained",
      "source": "tombstone",
      "purge": {
        "state": "GATING",
        "requestedBy": "token:123"
      }
    }
  ],
  "page_end": "end"
}

400

Section titled “400”

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

Media typeapplication/json

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

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

Always true.

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

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

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

string
reason

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

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

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

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

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

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

string
Allowed values: not_dropped not_drained
hint

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

string
state

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

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

403

Section titled “403”

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

Media typeapplication/json

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

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

Always true.

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

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

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

string
reason

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

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

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

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

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

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

string
Allowed values: not_dropped not_drained
hint

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

string
state

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

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

429

Section titled “429”

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

Media typeapplication/json

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

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

Always true.

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

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

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

string
reason

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

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

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

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

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

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

string
Allowed values: not_dropped not_drained
hint

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

string
state

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

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

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before the next request.

RateLimit-Limit
integer
>= 1

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

RateLimit-Remaining
integer

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

RateLimit-Reset
integer

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

500

Section titled “500”

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

Media typeapplication/json

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

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

Always true.

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

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

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

string
reason

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

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

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

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

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

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

string
Allowed values: not_dropped not_drained
hint

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

string
state

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

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

503

Section titled “503”

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

Media typeapplication/json

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

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

Always true.

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

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

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

string
reason

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

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

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

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

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

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

string
Allowed values: not_dropped not_drained
hint

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

string
state

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

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

Headers

Section titled “Headers”
Retry-After
integer