> ## Documentation Index
> Fetch the complete documentation index at: https://docs.world.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<table>
  <thead>
    <tr>
      <th className="p-2 text-left align-middle whitespace-nowrap">Code</th>
      <th className="p-2 text-left align-middle">Meaning</th>
      <th className="p-2 text-left align-middle">Typical action</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td className="p-2 align-middle whitespace-nowrap"><code>user\_rejected</code></td>
      <td className="p-2 align-middle">User cancelled in World App.</td>
      <td className="p-2 align-middle">Treat as user cancellation, allow retry.</td>
    </tr>

    <tr>
      <td className="p-2 align-middle whitespace-nowrap"><code>verification\_rejected</code></td>
      <td className="p-2 align-middle">Legacy rejection code (older bridge/app behavior).</td>
      <td className="p-2 align-middle">Handle same as <code>user\_rejected</code>.</td>
    </tr>

    <tr>
      <td className="p-2 align-middle whitespace-nowrap"><code>credential\_unavailable</code></td>
      <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 whitespace-nowrap"><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 whitespace-nowrap"><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 whitespace-nowrap"><code>malformed\_request</code></td>
      <td className="p-2 align-middle">Payload or configuration is invalid.</td>
      <td className="p-2 align-middle">Check <code>app\_id</code>, <code>rp\_context</code>, and request shape.</td>
    </tr>

    <tr>
      <td className="p-2 align-middle whitespace-nowrap"><code>invalid\_network</code></td>
      <td className="p-2 align-middle">Environment mismatch between app config and World App context.</td>
      <td className="p-2 align-middle">Align staging/production settings.</td>
    </tr>

    <tr>
      <td className="p-2 align-middle whitespace-nowrap"><code>inclusion\_proof\_pending</code></td>
      <td className="p-2 align-middle">Credential inclusion data is not ready yet.</td>
      <td className="p-2 align-middle">Retry later.</td>
    </tr>

    <tr>
      <td className="p-2 align-middle whitespace-nowrap"><code>inclusion\_proof\_failed</code></td>
      <td className="p-2 align-middle">Inclusion proof retrieval failed.</td>
      <td className="p-2 align-middle">Retry; if repeated, treat as operational incident.</td>
    </tr>

    <tr>
      <td className="p-2 align-middle whitespace-nowrap"><code>unexpected\_response</code></td>
      <td className="p-2 align-middle">Malformed or unsupported bridge/app response.</td>
      <td className="p-2 align-middle">Log diagnostics and retry once.</td>
    </tr>

    <tr>
      <td className="p-2 align-middle whitespace-nowrap"><code>connection\_failed</code></td>
      <td className="p-2 align-middle">Could not establish/maintain bridge communication.</td>
      <td className="p-2 align-middle">Check connectivity and bridge reachability.</td>
    </tr>

    <tr>
      <td className="p-2 align-middle whitespace-nowrap"><code>max\_verifications\_reached</code></td>
      <td className="p-2 align-middle">Action already verified the maximum allowed number of times.</td>
      <td className="p-2 align-middle">Treat as terminal business-rule outcome.</td>
    </tr>

    <tr>
      <td className="p-2 align-middle whitespace-nowrap"><code>failed\_by\_host\_app</code></td>
      <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 whitespace-nowrap"><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 whitespace-nowrap"><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 whitespace-nowrap"><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 whitespace-nowrap"><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 whitespace-nowrap"><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 whitespace-nowrap"><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 whitespace-nowrap"><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 whitespace-nowrap"><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 whitespace-nowrap"><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 whitespace-nowrap"><code>user\_presence\_failed</code></td>
      <td className="p-2 align-middle">Required user-presence check was not completed.</td>
      <td className="p-2 align-middle">Let the user retry the request.</td>
    </tr>

    <tr>
      <td className="p-2 align-middle whitespace-nowrap"><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 whitespace-nowrap"><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 whitespace-nowrap"><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 whitespace-nowrap"><code>timeout</code></td>
      <td className="p-2 align-middle">Client-side polling timeout.</td>
      <td className="p-2 align-middle">Extend timeout or let the user retry.</td>
    </tr>

    <tr>
      <td className="p-2 align-middle whitespace-nowrap"><code>cancelled</code></td>
      <td className="p-2 align-middle">Client-side cancellation (abort/task cancel/user close).</td>
      <td className="p-2 align-middle">Treat as neutral cancellation path.</td>
    </tr>
  </tbody>
</table>

## Handling errors

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

In JS and React, failed requests expose an `IDKitDebugReport` for triage. The widget `onError` callback receives it as a second `debugReport` argument for flow/bridge errors (host-app verify failures such as `failed_by_host_app` omit it); hooks expose `getDebugReport(): IDKitDebugReport | undefined`.

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 theme={null}
<IDKitRequestWidget
  // ...
  onError={(errorCode, debugReport) => {
    console.error("IDKit error", errorCode, debugReport);
  }}
/>
```

```tsx theme={null}
const flow = useIDKitRequest({ /* ... */ });

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