Skip to Content
Onshore is in early access. Don’t load real customer data until the items in Known limits are closed.
DevelopersTask guidesRetries and errors

Retries and errors

The error shape

Every error from the data API has the same body:

{ "error": { "code": "policy_denied", "message": "no rule allows detokenize on national_id", "policy": "support-agents" }, "request_id": "req_01HV3K8Z" }
  • Branch on code, never on message; messages can change.
  • Messages never contain a stored value, so errors are safe to log.
  • request_id finds the call in the audit log and is what support asks for.
  • policy names the access rule that decided, on refusals.

The SDKs turn this into one error type: VaultError (Node, Python, PHP), *vault.Error (Go), VaultException (Java).

Every code

StatusCodeMeaningSDK retriesWhat you do
0network_errorNo answer: DNS, TLS, connection refused or reset, timeoutYesAfter retries, fail closed and report
400invalid_requestMalformed body, missing or too-long purpose, unknown field, over 500 items, a check that doesn’t suit the field, unknown optionNoFix the code
401unauthenticatedBad signature, unknown or revoked key, expired assertion, reused jti, disabled account, clock skewNo (the next call signs again)Check the key and the server’s clock
403policy_deniedNo access rule allows this; or the IP isn’t on the key’s allowlistNoChange access rules, or don’t do it
403needs_business, needs_enterpriseA paid feature on an edition without it. Free on test vaultsNoSee Editions
404token_not_foundToken unknown, erased or expired; lookup found no matchNoTreat as “no such value”
404invalid_requestUnknown vault, record, person or flowNoCheck the ID
404not_foundDigital twin unknown or expiredNoCloak again
409duplicate_valueThe value already exists in a field marked uniqueNoIt’s already stored; look it up
413too_largeCloak or uncloak text over 256 KBNoSplit the text
422validation_failedValue fails its field’s format or check digitNoAsk the person to correct it
429rate_limitedA reveal limit, the lookup and check limit (60 a minute per caller), or a request limitYesSlow down; back off longer
500internalA bugYesReport with request_id
503key_service_unavailableThe key service is sealed or unreachable. Nothing was stored or decryptedYesWait; alert your operators
503detection_not_readyDetection rules still loading after a restartYesWait a few seconds

Secure components add invalid_client_token (unknown, expired, used or wrong origin), forbidden and origin_not_allowed (origin not listed).

What the SDKs retry

Network failures, timeouts, 429 and 5xx are retried with exponential backoff and jitter (about 100–200 ms doubling to 2 s), 4 attempts in total by default. Everything else is returned at once. Change the number with maxAttempts (max_attempts in Python, MaxAttempts in Go). Go also stops waiting when its context is cancelled.

Is it safe to retry?

A request can succeed in the vault but its response be lost (a timeout, a dropped connection). Whether retrying is safe then depends on the call:

CallSafe to retry?Why
tokenize on a deterministic fieldYesSame value, same token: a retry returns the existing token with existing: true
tokenize on a cell fieldMostlyA retry stores the value again under a new token. The first token is orphaned: harmless, but it’s an extra copy. Avoid by making the field unique, or tokenizing deterministic fields where duplicates matter
tokenize on a unique cell fieldRetry returns 409 duplicate_valueThe first attempt stored it. Use lookup to get its token
insertRecordLike tokenize for its fields
detokenize, getRecord, exportSubjectYesReads. Each attempt is audited, so a retry shows as two reveals
lookup, residentCheck, detect (without tokenize)YesReads, but each counts against rate limits
updateValueYesSetting the same value twice is the same as once
restrictSubjectYesSets a state
eraseSubjectYesIf the first attempt went through, the retry gets 404 invalid_request (the person is gone): treat that as done
createClientTokenYesAn unused client token simply expires
cloak with keepDaysYesA retry may leave an extra twin, which expires

Patterns

Fail closed on reveals

async function safeReveal(token: string, purpose: string): Promise<string | null> { try { const [r] = await vault.detokenize(VAULT, [token], purpose); return r.decision === "plaintext" || r.decision === "masked" ? r.value! : null; } catch (e) { log.warn("reveal failed", { code: (e as VaultError).code, requestId: (e as VaultError).requestId }); return null; // show "unavailable", never the token or a cached copy } }

Don’t fail open on stores

If tokenize fails, don’t save the raw value “for now”. Return an error to the caller, or queue the work with the value held only in memory or an encrypted queue, and retry.

Back off on 429 for jobs

The SDKs’ few quick retries suit interactive calls. A batch job hitting reveal limits should pause longer:

for (const batch of batches) { for (let wait = 5_000; ; wait = Math.min(wait * 2, 300_000)) { try { await process(batch); break; } catch (e) { if (e instanceof VaultError && e.code === "rate_limited") { await sleep(wait); continue; } throw e; } } }

Treat 401 as a configuration problem

A 401 after working calls usually means the key was revoked or rotated, or the server’s clock has drifted (assertions are rejected if their times are off by more than a few minutes). Check NTP, then the key. The SDK signs a fresh assertion on the next call, so a one-off 401 during a rotation fixes itself.

Map errors for your own API

Vault codeYour API returns
validation_failed422, “check this value”
duplicate_value409
token_not_found404 or 410
policy_denied403
rate_limited429 with Retry-After
key_service_unavailable, network_error, internal503

Never pass the vault’s message straight to end users; write your own.

Limits at a glance

LimitValue
Items per tokenize or detokenize request500 (the SDKs batch for you)
Purpose500 characters
detect and flow check text1 MiB
cloak and uncloak text256 KB
Lookups and resident checks60 a minute per caller
Client token lifetime120 s default, 600 s maximum
Client token scope10 fields (collect), 20 tokens (reveal)
Bearer token lifetime15 minutes
Assertion lifetime5 minutes at most; each jti once
Digital twin1 to 365 days
Authentication failures120 a minute per address by default
Last updated on