Error Codes

Reference for IDKit request error codes and handling guidance across JS, React, Kotlin, and Swift.

This page focuses on IDKit SDK and bridge error codes returned during request flows.

Canonical codes

Code	Meaning	Typical action
user_rejected	User cancelled in World App.	Treat as user cancellation, allow retry.
verification_rejected	Legacy rejection code (older bridge/app behavior).	Handle same as user_rejected.
credential_unavailable	Requested credential type is not available for that user.	Offer fallback credential policy or explain requirement.
world_id_4_not_available	World ID 4.0 credential is not available for that user.	Use a compatible fallback request or explain the World ID 4.0 requirement.
world_id_3_not_available	World ID 3.0 credential is not available for that user.	Use a compatible fallback request or explain the World ID 3.0 requirement.
malformed_request	Payload or configuration is invalid.	Check app_id, rp_context, and request shape.
invalid_network	Environment mismatch between app config and World App context.	Align staging/production settings.
inclusion_proof_pending	Credential inclusion data is not ready yet.	Retry later.
inclusion_proof_failed	Inclusion proof retrieval failed.	Retry; if repeated, treat as operational incident.
unexpected_response	Malformed or unsupported bridge/app response.	Log diagnostics and retry once.
connection_failed	Could not establish/maintain bridge communication.	Check connectivity and bridge reachability.
max_verifications_reached	Action already verified the maximum allowed number of times.	Treat as terminal business-rule outcome.
failed_by_host_app	Host app callback failed while processing a successful proof.	Fix host callback/backend logic and retry.
invalid_rp_signature	RP signature could not be verified.	Check the RP signing key, nonce, timestamps, action, and signed message.
nullifier_replayed	Nullifier was already used for this action.	Treat as an already-verified outcome; do not retry the same action as a new verification.
duplicate_nonce	RP reused a signature nonce.	Generate a fresh nonce and signed RP context for each request.
unknown_rp	RP is not known to the registry.	Check the registered RP ID and app configuration.
inactive_rp	RP is registered but inactive.	Reactivate or reconfigure the RP before retrying.
timestamp_too_old	RP request timestamp is too old.	Generate a new signed RP context with a current timestamp.
timestamp_too_far_in_future	RP request timestamp is too far in the future.	Fix server clock skew and generate a new signed RP context.
invalid_timestamp	RP request timestamp is invalid.	Check timestamp format and regenerate the signed RP context.
rp_signature_expired	RP signature has expired.	Request a fresh RP signature before starting verification.
identity_attributes_not_matched	User identity attributes did not match the requested constraints.	Show an eligibility fallback or adjust the requested attribute constraints.
generic_error	Catch-all unknown failure.	Log details and retry with backoff.
invalid_rp_id_format	RP ID is malformed.	Use the registered rp_… ID from your app configuration.
timeout	Client-side polling timeout.	Extend timeout or let the user retry.
cancelled	Client-side cancellation (abort/task cancel/user close).	Treat as neutral cancellation path.

Handling errors

Widgets expose an onError callback. Hooks expose isError and errorCode on the result object.

Version availability errors such as world_id_4_not_available and world_id_3_not_available are terminal for the current user and request. Retrying the same request usually returns the same result; change the requested credential policy or show a user-facing fallback instead.

In JS and React, match these with IDKitErrorCodes. Kotlin and Swift expose the same raw values through their IDKitErrorCode enums.

<IDKitRequestWidget
  // ...
  onError={(errorCode) => {
    console.error("IDKit error", errorCode);
  }}
/>

const flow = useIDKitRequest({ /* ... */ });

if (flow.isError) {
  console.error(flow.errorCode);
}