This page focuses on IDKit SDK and bridge error codes returned during request/session 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. |
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. |
generic_error | Catch-all unknown failure. | Log details and retry with backoff. |
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. |
SDK coverage notes
- JavaScript core / React: emit all codes above (including
timeout and cancelled).
- Swift:
IDKitErrorCode includes all codes above.
- Kotlin:
StatusWrapper.Failed carries app-level errors; timeout/cancellation handling is usually host-driven.
verification_rejected is retained for backward compatibility. Newer flows typically return user_rejected.
Handling pattern
import { IDKitErrorCodes } from "@worldcoin/idkit-core";
function classify(error: IDKitErrorCodes): "retry" | "terminal" | "cancelled" {
if (error === IDKitErrorCodes.MaxVerificationsReached) return "terminal";
if (error === IDKitErrorCodes.UserRejected || error === IDKitErrorCodes.Cancelled) {
return "cancelled";
}
return "retry";
}
switch error {
case .maxVerificationsReached:
// terminal business outcome
break
case .userRejected, .cancelled:
// user-driven cancel path
break
default:
// retry/incident path
break
}
Also check
