Troubleshooting

Connection

Symptom	Cause
Wrong chain ID	MetaMask needs the hex form, 0xbc1, not 3009
Cannot reach the RPC	Check https://rpc.testnet.kriptonyx.com. Hosts without testnet are not in service
Balance reads zero	Fund from the faucet, and check you are on chain 3009
Gas price estimates zero	Expected. The minimum gas price is 0aknyx

Transactions

Error	Cause
insufficient funds	Balance below value plus gas
nonce too low	A transaction with that nonce already landed
replacement transaction underpriced	Replacing a pending transaction needs a higher price
execution reverted	The contract rejected the call. Read the reason string
Gas estimation fails	The call would revert. Estimation simulates first — fix the revert, do not raise the limit

AMM

Error	Cause
INSUFFICIENT_OUTPUT_AMOUNT	Slippage bound too tight, or the price moved. Re-quote with getAmountsOut
INSUFFICIENT_INPUT_AMOUNT	Input is zero, or below what the pool accepts
TRANSFER_FROM_FAILED	The router has no allowance. Approve the token first
EXPIRED	The deadline passed before the transaction mined
INSUFFICIENT_LIQUIDITY	The pool cannot fill a trade that size
Output is wrong by ~0.1%	You assumed a 0.3% fee. It is 0.2% — 998/1000
getPair returns the zero address	The pair does not exist yet
Locally computed pair address is wrong	Wrong INIT_CODE_PAIR_HASH. Take it from the deployed factory
massUpdatePools reverts	A farm pool's pair does not exist on chain — see Yield farming
Farm rewards read zero	KNP is not funded yet

APIs

Symptom	Cause
Every error looks like a network failure	The body is being parsed before the status is checked. See Errors
401 from the Platform REST API	Password missing, or wallet-level auth required where user-level was supplied
401 with no detail	Deliberate. Failures do not reveal whether an account exists
429	Rate limited. Check the RateLimit-* headers
503	The feature is not configured on this deployment
Log query fails	More than 10,000 blocks requested. Use the chain data API

Webhooks

Symptom	Cause
Nothing arrives	Endpoint not returning 2xx within 10 s, subscription inactive, or the event filter excludes it
Signature never matches	Hashing re-serialised JSON rather than the raw body. See Webhooks
Events arrive twice	Expected. Delivery is at-least-once — deduplicate on X-Bridge-Delivery
Stopped after a while	Attempts exhausted, or the subscription was auto-disabled after repeated failures
503 on subscription routes	No admin token configured. The routes refuse rather than run unauthenticated

Check delivery history first — it records the status, error and attempt count for every attempt:

curl -s -H "Authorization: Bearer $BRIDGE_ADMIN_TOKEN" \
  "https://bridge.testnet.kriptonyx.com/api/webhook/subscriptions/<id>/deliveries?failed=true"

Bridge

Symptom	Cause
Deposit not detected	Wrong asset or wrong chain for that deposit address, or sent after expiry
Status stuck at pending_deposit	The monitor polls every 20 seconds; if longer, the deposit did not arrive where expected
failed with insufficient funds	The payout wallet lacked gas or reserves on the target chain
Funds not refunded	No refund_address was supplied

WebSocket

Symptom	Cause
Connection closes after ~60 s	No heartbeat. Phoenix closes idle sockets
Missed events after a drop	Reconcile with GET /api/swap/:id/events or the chain data API
Address topic silent	Address topics use the lowercase form

Amounts

Symptom	Cause
Value off by orders of magnitude	Mixing base units and display units. See KNYX and denominations
Large balance slightly wrong	Number used instead of BigInt. Precision is lost above 253
Token amount wrong	Assumed 18 decimals. Read decimals() — bridged USDT uses 6, BTC uses 8

Still stuck

Every state transition is recorded on chain or in the API. Quote the transaction hash, the swap ID or the subscription ID — that is what makes a problem diagnosable.