Skip to content
QuantCDN

Get the key that holds a value of a unique index

GET
/api/v2/organizations/{organization}/projects/{project}/kv/{store_id}/indexes/{index_name}/lookup
curl --request GET \
  --url 'https://dashboard.quantcdn.io/api/v2/organizations/test-org/projects/test-project/kv/test-org-test-project-orders/indexes/byCustomer/lookup?equals=%7B%22email%22%3A%22ann%40example.com%22%7D&reveal=false' \
  --header 'Authorization: Bearer <token>'

Unique indexes only; the index must be ACTIVE (409 INDEX_NOT_READY while BUILDING). Strongly consistent. An expired owner, or an owner that no longer holds the value, is 404 KEY_NOT_FOUND. An owner that is an entry of a ledger in the retired subject format is 409 LEDGER_FORMAT_RETIRED (not retryable). A ledger entry needs the ledger_read permission (and, for a token with a scope list, the kv:ledger:read scope; a legacy token without a scope list needs the permission only) (403 PERMISSION_DENIED); its personal fields are [PERSONAL] unless the role has ledger_reveal and reveal=true (each reveal is logged as kv.ledger.reveal). reveal is a portal option and is not sent to the KV service. An empty object {} in a value stays {}, but a ledger entry whose whole value is {} reads [PERSONAL] (fail closed). Secret values are write-only through the API: a value stored as a secret (encrypted true) reads [ENCRYPTED]; read it in an edge function.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “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
index_name
required
string
/^[A-Za-z][A-Za-z0-9_]{0,63}$/
Example
byCustomer

Query Parameters

Section titled “Query Parameters”
equals
required
string
<= 8192 characters

A JSON object that gives a JSON scalar for exactly the index fields. Values are type-tagged (1 and “1” differ).

Example
{"email":"ann@example.com"}
reveal
boolean

Ledger rows only: return personal fields in clear. Needs the ledger_reveal permission; each reveal is logged. Without it, personal fields are redacted.

Responses

Section titled “Responses”

200

Section titled “200”

The key that holds the value.

Media typeapplication/json

The key that holds the value, with the same body as a key read. A ledger entry adds ledger; its personal fields are [PERSONAL] (listed in personal) unless the caller has ledger_reveal and sends reveal=true.

object
key
required
string
value

The stored JSON value (any JSON type).

status
required
string
Allowed values: found
message
required
string
created_at
string format: date-time
updated_at
string format: date-time
expires_at

Epoch seconds. Absent when the key does not expire.

integer
encrypted
boolean
version

ULID, new on every write. Absent on ledger entries.

string
ledger

Ledger metadata of an entry. Present only on ledger entries.

object
name

The ledger name.

string
id
required

A ULID, a hyphen and the two-digit shard.

string
shard
required
string
/^[0-9]{2}$/
seq
required

The sequence number in the shard.

integer
>= 1
at
required

Server time, epoch milliseconds.

integer format: int64
hash
required
string
prevHash
required

The hash of the previous entry in the same shard.

string
source

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

object
type
required
string
Allowed values: platform api dashboard edge
principal
required
string
<= 256 characters /^[A-Za-z0-9][A-Za-z0-9._:@/-]*$/
subject

Present when the ledger has a subjectField: what the subject field holds.

string
Allowed values: pseudonym clear
personal

Ledger entries only: the personal fields the portal replaced with [PERSONAL] (* = the whole value).

Array<string>
Example
{
  "key": "user:1",
  "value": {
    "email": "ann@example.com"
  },
  "status": "found",
  "message": "Key found",
  "created_at": "2026-10-16T00:00:00.000Z",
  "updated_at": "2026-10-16T00:00:00.000Z",
  "version": "01JB2Z6V8Q3M4N5P6R7S8T9V0W"
}

400

Section titled “400”

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

Media typeapplication/json

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

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

Always true.

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

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

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

string
reason

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

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

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

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

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

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

string
Allowed values: not_dropped not_drained
hint

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

string
state

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

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

403

Section titled “403”

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

Media typeapplication/json

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

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

Always true.

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

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

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

string
reason

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

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

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

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

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

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

string
Allowed values: not_dropped not_drained
hint

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

string
state

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

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

404

Section titled “404”

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

Media typeapplication/json

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

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

Always true.

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

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

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

string
reason

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

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

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

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

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

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

string
Allowed values: not_dropped not_drained
hint

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

string
state

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

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

409

Section titled “409”

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

Media typeapplication/json

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

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

Always true.

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

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

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

string
reason

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

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

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

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

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

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

string
Allowed values: not_dropped not_drained
hint

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

string
state

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

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

429

Section titled “429”

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

Media typeapplication/json

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

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

Always true.

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

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

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

string
reason

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

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

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

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

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

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

string
Allowed values: not_dropped not_drained
hint

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

string
state

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

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

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before the next request.

RateLimit-Limit
integer
>= 1

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

RateLimit-Remaining
integer

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

RateLimit-Reset
integer

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

500

Section titled “500”

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

Media typeapplication/json

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

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

Always true.

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

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

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

string
reason

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

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

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

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

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

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

string
Allowed values: not_dropped not_drained
hint

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

string
state

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

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

503

Section titled “503”

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

Media typeapplication/json

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

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

Always true.

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

True when the same request can be sent again safely.

boolean
key

CONFLICT: the key the condition named.

string
currentVersion

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

string
reason

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

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

LEDGER_RETAINED: when the archive retention ends.

string format: date-time
activeAfter

LEDGER_NOT_READY: when the PENDING ledger can become ACTIVE.

string format: date-time
collection

LEDGER_RETAINED (unarchived): the collection with unarchived entries.

string
shard

LEDGER_RETAINED (unarchived): the shard with unarchived entries.

string
operation

Transact: the index of the failing operation.

integer
index

UNIQUE_VIOLATION: the unique index.

string
existingKey

UNIQUE_VIOLATION: the key that holds the value.

string
ledgers

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

Array<object>
object
name
required

The ledger name.

string
state
required

The ledger state (PENDING, ACTIVE or DROPPED).

string
reason
required

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

string
Allowed values: not_dropped not_drained
hint

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

string
state

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

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

Headers

Section titled “Headers”
Retry-After
integer