World Developer Docs

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.
`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.

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

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

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

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