Credential issues

​

Issuance

​

Credential stuck in WAIT_ONCHAIN

• Poll the status endpoint with exponential backoff (start at 1 second, double each attempt, cap at 30 seconds).
• If the credential remains in WAIT_ONCHAIN for more than 5 minutes, check the Moca Chain block explorer for chain health.
• Do not re-issue the credential while it is pending — use the status endpoint to wait.

​

Issue on Behalf returns 400

• Verify issuerDid, credentialId, and credentialSubject are all present and correctly typed.
• Ensure credentialSubject matches the schema definition exactly. Extra fields or wrong types will be rejected.
• Check the response body for a specific error message.

​

Issue on Behalf returns 409

• User consent rejected: The user has previously declined credentials from your partner account. Contact the user or wait for them to re-consent.
• Duplicate credential with onDuplicate: "ignore": A credential already exists for this user + schema combination. If you need to update it, use onDuplicate: "revoke".

​

Credential not visible to user after issuance

• Confirm the credential status is ONCHAIN via the status endpoint.
• For Issue on Behalf, newly created users see issued credentials when they first log in. They may be prompted to accept or reject credentials.
• Verify the user’s email matches the email claim in your Partner JWT.

​

Verification

​

Verification returns “no matching credential”

• The user may not have a credential matching the verification program’s schema. Check that:
  • The credential was issued using the correct issuance program.
  • The credential has not been revoked.
  • The verification program’s schema matches the issuance program’s schema.

​

Verification fails with “proof invalid”

• The credential may have been tampered with or the on-chain anchor may not match.
• If the credential was recently issued, ensure it has reached ONCHAIN status before attempting verification.
• Check that the credential has not expired (expirationDate in the status response).

​

User declines verification

• The SDK prompts users for consent before presenting a credential. If the user declines, the verification result will indicate failure.
• Your app should handle this gracefully — show a message explaining why the credential is needed and offer to retry.

​

Schema issues

​

”Schema not found” error

• Verify the schema exists in the Developer Dashboard (Issuer > Schemas).
• Ensure the credentialId (Issuance Program ID) references a published program, not a draft.

​

Schema mismatch between issuance and verification

• If a verification program rejects credentials that were successfully issued, the issuance and verification programs may reference different schema versions.
• Check both programs in the Developer Dashboard and ensure they point to the same schema.

​

CAK-specific issues

​

Encrypted data not decrypting for verifier

• Verify the user has granted consent in the SDK UI.
• Ensure the verification program has CAK required enabled.
• Check that the issuer’s CAK callback URL is correctly configured and returning 200 responses.