Retries and timeouts

The SDK retries temporary failures. Do not put your own retry loop around an SDK call.

What the SDK retries

Call	Retries after
registerNonPiiRegisterNonPiiAsyncregister_non_pii	A network failure, or a 408, 429 or 5xx response
registerNonPiiBatchRegisterNonPiiBatchAsyncregister_non_pii_batch	A network failure, or a 408, 429 or 5xx response
registerAndBuildBarcodeRegisterAndBuildBarcodeAsyncregister_and_build_barcode	A 429 response only

The Verifiabl reference is the idempotency key. A retry sends the same records with the same references. In a batch, records that the API registered before return duplicate. Refer to Idempotency and retries.

The SDK does not retry other responses, for example 400 or 409. After a 401 response, the SDK gets a new token and sends the request one more time. In a pay run, the SDK does not retry a record that has an error result.

How long the SDK waits

Before a retry, the SDK waits for the time in the Retry-After response header. If there is no header, it waits for an exponential backoff with a random part. The backoff starts at 0.5 seconds and doubles for each retry, to a maximum of 8 seconds.

By default, the SDK makes 2 retries, so a call has a maximum of 3 attempts. To change the number of retries, set maxRetriesMaxRetriesmax_retries: on the client.

Set the timeout

The timeout applies to the full call, not to each attempt. It includes the token request, all attempts, and the waits between them. If the first attempt is slow, no time can be left for a retry. Then the SDK reports a timeout.

The default timeout is 30 seconds. For a pay run batch of up to 1,000 records, set timeoutMs: 120_000Timeout = TimeSpan.FromSeconds(120)timeout: 120 on the client.

The timeout applies to all calls from the client. To keep a shorter timeout for single registrations, create a second client for pay runs.

To set the timeout for one call, give registerNonPii or registerNonPiiBatch a second argument, for example { timeoutMs: 120_000 }. To stop a call before its timeout, add a signal from an AbortController to the same argument.

To stop a call before its timeout, pass a CancellationToken. The SDK then throws OperationCanceledException.

The SDK checks the timeout between operations. The built-in transport applies the time that remains to each connection, read and write. A slow DNS lookup, or a response that keeps sending data, can make a call take longer than the timeout. For a strict limit, give a transport: that limits the full request to the timeout: value that it receives.

If the retries do not succeed

The SDK throws an error when all attempts fail or the timeout expires. Then the API can have registered none, some or all of the records.

The SDK retries a 429 response for a short time only. If the error has the status 429, wait for 60 seconds or more. Then send the same records again. Refer to Rate limits.

To try again later, send the same records. In a batch, records that the API registered before return duplicate. Refer to Register again later.

For the errors that the SDK throws, refer to Handle errors.

Register again later

To register a payslip again later, for example after your process stops, keep two values from the prepared payslip:

Value	Name
Registration	registrationRegistrationregistration
Ciphertext	barcodeParts(verifiablReference).encryptedPiiBarcodeParts(VerifiablReference).EncryptedPiibarcode_parts(verifiabl_reference).fetch(:encrypted_pii)

Send the same registration again. Then make the QR code from the returned reference and the saved ciphertext.