docs(idkit): document error codes

world-id/idkit/error-codes.mdx

@@ -33,6 +33,16 @@ This page focuses on IDKit SDK and bridge error codes returned during request fl
       <td className="p-2 align-middle">Requested credential type is not available for that user.</td>
       <td className="p-2 align-middle">Offer fallback credential policy or explain requirement.</td>
     </tr>
+    <tr>
+      <td className="p-2 align-middle"><code>world_id_4_not_available</code></td>
+      <td className="p-2 align-middle">World ID 4.0 credential is not available for that user.</td>
+      <td className="p-2 align-middle">Use a compatible fallback request or explain the World ID 4.0 requirement.</td>
+    </tr>
+    <tr>
+      <td className="p-2 align-middle"><code>world_id_3_not_available</code></td>
+      <td className="p-2 align-middle">World ID 3.0 credential is not available for that user.</td>
+      <td className="p-2 align-middle">Use a compatible fallback request or explain the World ID 3.0 requirement.</td>
+    </tr>
     <tr>
       <td className="p-2 align-middle"><code>malformed_request</code></td>
       <td className="p-2 align-middle">Payload or configuration is invalid.</td>
@@ -73,11 +83,66 @@ This page focuses on IDKit SDK and bridge error codes returned during request fl
       <td className="p-2 align-middle">Host app callback failed while processing a successful proof.</td>
       <td className="p-2 align-middle">Fix host callback/backend logic and retry.</td>
     </tr>
+    <tr>
+      <td className="p-2 align-middle"><code>invalid_rp_signature</code></td>
+      <td className="p-2 align-middle">RP signature could not be verified.</td>
+      <td className="p-2 align-middle">Check the RP signing key, nonce, timestamps, action, and signed message.</td>
+    </tr>
+    <tr>
+      <td className="p-2 align-middle"><code>nullifier_replayed</code></td>
+      <td className="p-2 align-middle">Nullifier was already used for this action.</td>
+      <td className="p-2 align-middle">Treat as an already-verified outcome; do not retry the same action as a new verification.</td>
+    </tr>
+    <tr>
+      <td className="p-2 align-middle"><code>duplicate_nonce</code></td>
+      <td className="p-2 align-middle">RP reused a signature nonce.</td>
+      <td className="p-2 align-middle">Generate a fresh nonce and signed RP context for each request.</td>
+    </tr>
+    <tr>
+      <td className="p-2 align-middle"><code>unknown_rp</code></td>
+      <td className="p-2 align-middle">RP is not known to the registry.</td>
+      <td className="p-2 align-middle">Check the registered RP ID and app configuration.</td>
+    </tr>
+    <tr>
+      <td className="p-2 align-middle"><code>inactive_rp</code></td>
+      <td className="p-2 align-middle">RP is registered but inactive.</td>
+      <td className="p-2 align-middle">Reactivate or reconfigure the RP before retrying.</td>
+    </tr>
+    <tr>
+      <td className="p-2 align-middle"><code>timestamp_too_old</code></td>
+      <td className="p-2 align-middle">RP request timestamp is too old.</td>
+      <td className="p-2 align-middle">Generate a new signed RP context with a current timestamp.</td>
+    </tr>
+    <tr>
+      <td className="p-2 align-middle"><code>timestamp_too_far_in_future</code></td>
+      <td className="p-2 align-middle">RP request timestamp is too far in the future.</td>
+      <td className="p-2 align-middle">Fix server clock skew and generate a new signed RP context.</td>
+    </tr>
+    <tr>
+      <td className="p-2 align-middle"><code>invalid_timestamp</code></td>
+      <td className="p-2 align-middle">RP request timestamp is invalid.</td>
+      <td className="p-2 align-middle">Check timestamp format and regenerate the signed RP context.</td>
+    </tr>
+    <tr>
+      <td className="p-2 align-middle"><code>rp_signature_expired</code></td>
+      <td className="p-2 align-middle">RP signature has expired.</td>
+      <td className="p-2 align-middle">Request a fresh RP signature before starting verification.</td>
+    </tr>
+    <tr>
+      <td className="p-2 align-middle"><code>identity_attributes_not_matched</code></td>
+      <td className="p-2 align-middle">User identity attributes did not match the requested constraints.</td>
+      <td className="p-2 align-middle">Show an eligibility fallback or adjust the requested attribute constraints.</td>
+    </tr>
     <tr>
       <td className="p-2 align-middle"><code>generic_error</code></td>
       <td className="p-2 align-middle">Catch-all unknown failure.</td>
       <td className="p-2 align-middle">Log details and retry with backoff.</td>
     </tr>
+    <tr>
+      <td className="p-2 align-middle"><code>invalid_rp_id_format</code></td>
+      <td className="p-2 align-middle">RP ID is malformed.</td>
+      <td className="p-2 align-middle">Use the registered <code>rp_...</code> ID from your app configuration.</td>
+    </tr>
     <tr>
       <td className="p-2 align-middle"><code>timeout</code></td>
       <td className="p-2 align-middle">Client-side polling timeout.</td>
@@ -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. 
+
 ```tsx
 <IDKitRequestWidget
   // ...