From fdce0292621c4730d90a180c43dd087400c9a5ec Mon Sep 17 00:00:00 2001
From: Takis Kakalis <80459599+Takaros999@users.noreply.github.com>
Date: Thu, 14 May 2026 20:38:07 +0900
Subject: [PATCH 1/2] docs: document idkit error codes
---
world-id/idkit/error-codes.mdx | 69 ++++++++++++++++++++++++++++++++++
1 file changed, 69 insertions(+)
diff --git a/world-id/idkit/error-codes.mdx b/world-id/idkit/error-codes.mdx
index b45e0c6..de9cce2 100644
--- a/world-id/idkit/error-codes.mdx
+++ b/world-id/idkit/error-codes.mdx
@@ -33,6 +33,16 @@ This page focuses on IDKit SDK and bridge error codes returned during request fl
| 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. |
@@ -73,11 +83,66 @@ This page focuses on IDKit SDK and bridge error codes returned during request fl
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. |
@@ -95,6 +160,10 @@ This page focuses on IDKit SDK and bridge error codes returned during request fl
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. Some native protocol responses may use `nullifier_replay`; IDKit normalizes that to the canonical `nullifier_replayed` code.
+
```tsx
Date: Thu, 14 May 2026 21:10:20 +0900
Subject: [PATCH 2/2] remove
---
world-id/idkit/error-codes.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/world-id/idkit/error-codes.mdx b/world-id/idkit/error-codes.mdx
index de9cce2..411bd80 100644
--- a/world-id/idkit/error-codes.mdx
+++ b/world-id/idkit/error-codes.mdx
@@ -162,7 +162,7 @@ Widgets expose an `onError` callback. Hooks expose `isError` and `errorCode` on
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. Some native protocol responses may use `nullifier_replay`; IDKit normalizes that to the canonical `nullifier_replayed` code.
+In JS and React, match these with `IDKitErrorCodes`. Kotlin and Swift expose the same raw values through their `IDKitErrorCode` enums.
```tsx