Error codes
Canonical errors surfaced when opening a referral link and minting a session.
The terminal error codes the Shop shows when it cannot establish a session from a referral link.
| Code | HTTP | Cause | Fix |
|---|---|---|---|
NO_PARTNER | — (client) | The link carries no provider slug (and no saved referral to re-mint from) | Ensure the link starts with your /<slug>. Don't open an inner route directly — always open the entry link. |
INVALID_LINK | 401 | Mint rejected: bad/expired signature, unknown/inactive slug, or an unlinked/inactive sale_channel. The backend returns a uniform 401 (anti-enumeration). | Recompute sign (clock skew ±5 min). Verify slug/channel provisioning with Bluecom ops. |
VERIFICATION_FAILED | 401 | Identity sign-in failed on a surface that requires auth (WebView / Telegram / KBZPay) | Check the credential (HMAC trio, initData, or kbzpay_token) and secret for the right environment. |
NETWORK_ERROR | — (client) | The bootstrap hit an unexpected error (network, mint timeout) | Retry; if it persists, check connectivity to the Shop host. |
Debugging checklist
Work through this list top-to-bottom before escalating to Bluecom ops.
- Does the link start with your correct
/<slug>(not an inner route)? - Is
tsin seconds, not milliseconds? - Is the signed string exactly
uid:ts— no spaces, no JSON? - Is
signlowercase hex? - Is
partnerSecretfrom the correct environment (staging vs production)? - Is the
sale_channel(if pinned) linked + active for yourslug? - Is server time within ±5 minutes of UTC?
Clock skew
Most signature-related INVALID_LINK errors in production come from server clocks drifting more than 5 minutes. Ensure your server syncs via NTP.