Troubleshooting

What You’ll FindThis page covers:

Authentication and API key issues
User onboarding and KYC problems
Card creation and usage errors
Transaction declines and failures
Webhook delivery issues
MCP connection problems

Time to resolve: Most issues can be resolved in minutes

Authentication Issues

Error: 'Invalid API key'

Symptoms:

HTTP 401 response
Error message: “Invalid API key” or “Unauthorized”

Causes:

Typo in API key
Using wrong environment key (dev vs live)
Key has been revoked

Solutions:

Verify the key in your dashboard matches what you’re using
Check you’re using lk_dev_ for sandbox and lk_live_ for production
Ensure the key hasn’t been revoked
Check for extra whitespace or newlines in the key

# Verify your key works
curl -I https://api.ledger.so/v1/users \
  -H "Api-Key: lk_live_your_key"

# Should return 200, not 401

Error: 'Missing Api-Key header'

Symptoms:

HTTP 401 response
Error message: “Missing Api-Key header”

Causes:

Header name is wrong (case-sensitive)
Header not being sent

Solutions:

Use exact header name: Api-Key (capital A, capital K)
Check your HTTP client is sending headers correctly

# Correct
-H "Api-Key: lk_live_xxx"

# Wrong (won't work)
-H "api-key: lk_live_xxx"
-H "API-KEY: lk_live_xxx"
-H "Authorization: Bearer lk_live_xxx"

Error: 'Agent token not authorized for this endpoint'

Symptoms:

HTTP 403 response when using agent token

Causes:

Agent tokens can only access agent-scoped endpoints
Trying to access admin endpoints (user management, etc.)

Solutions:

Use API key for admin operations
Use agent token only for: card details, intents, transactions

Endpoint	API Key	Agent Token
`/v1/users`	Yes	No
`/v1/agents`	Yes	No
`/v1/cards/{id}/details`	Yes	Yes
`/v1/cards/{id}/intents`	Yes	Yes
`/v1/transactions`	Yes	Yes (own only)

User & KYC Issues

User stuck in 'pending' verification status

Symptoms:

User completed KYC flow but status remains “pending”
Not receiving user.approved webhook

Causes:

KYC requires manual review
Document quality issues
Information mismatch

Solutions:

Check verification status via API:

curl https://api.ledger.so/v1/verification/user/user_xxx \
  -H "Api-Key: lk_live_xxx"

If status is manualReview, wait for review (usually < 24 hours)
If status is documentRequired, user needs to re-upload documents
Contact support if stuck > 48 hours

KYC verification URL expired

Symptoms:

User clicks verification link and sees “expired” error

Causes:

Verification URLs expire after 7 days

Solutions:

Generate a new verification URL:

curl https://api.ledger.so/v1/verification/user/user_xxx/link \
  -H "Api-Key: lk_live_xxx"

Error: 'User not approved for spending'

Symptoms:

Cannot create agents or cards
Error mentions user not approved

Causes:

User hasn’t completed KYC
KYC was rejected

Solutions:

Check user’s application status:

curl https://api.ledger.so/v1/users/user_xxx \
  -H "Api-Key: lk_live_xxx"

If applicationStatus is not “approved”, user must complete/retry KYC
If rejected, check rejectionReason and advise user

Card Issues

Error: 'Insufficient balance' when creating card

Symptoms:

Card creation fails
Error: “Insufficient balance”

Causes:

User’s available balance is less than card’s maxAmount
Funds are tied up in pending transactions

Solutions:

Check user’s balance:

curl https://api.ledger.so/v1/balances/user_xxx \
  -H "Api-Key: lk_live_xxx"

Look at available (not total) balance
Either:
- Reduce card’s maxAmount
- Have user deposit more funds
- Wait for pending transactions to settle

Error: 'Declare intent first' when getting card details

Symptoms:

POST /v1/cards/{id}/details returns error
Message: “Intent declaration required”

Causes:

No intent declared for this card
Intent expired (intents expire after 1 hour)

Solutions:

Declare intent first:

curl -X POST https://api.ledger.so/v1/cards/card_xxx/intents \
  -H "Api-Key: lk_live_xxx" \
  -d '{
    "summary": "Buy headphones",
    "amount": 15000,
    "merchantText": "Amazon"
  }'

Then request card details
Note: intents expire after 1 hour if details aren’t accessed

Card shows 'frozen' status unexpectedly

Symptoms:

Card transactions are declining
Card status is “frozen”

Causes:

Spending limit exceeded
Risk engine triggered freeze
Manual freeze via API/dashboard

Solutions:

Check card status and reason:

curl https://api.ledger.so/v1/cards/card_xxx \
  -H "Api-Key: lk_live_xxx"

If limit exceeded: increase limit or create new card

If risk freeze: review in dashboard, unfreeze if appropriate:

curl -X POST https://api.ledger.so/v1/cards/card_xxx/unfreeze \
  -H "Api-Key: lk_live_xxx"

Transaction Issues

Transaction declined: Insufficient funds

Symptoms:

Transaction fails at merchant
Decline reason: insufficient funds

Causes:

User balance too low
Card’s maxAmount exceeded
Pending transactions holding funds

Solutions:

Check balance and card limits
Remember: card’s maxAmount is per-transaction limit
For multi-use cards, check if daily/monthly limits are exceeded

Transaction triggered merchant drift alert

Symptoms:

Transaction completes but triggers risk.merchant_drift webhook
Card may be frozen (if drift action is freeze_card)

Causes:

Multi-use card used at a different merchant than the first transaction
Merchant drift detection is enabled by default for multi-use cards

Solutions:

If legitimate multi-merchant use, disable drift detection when creating the card:

curl -X POST https://api.ledger.so/v1/agents/$AGENT_ID/cards \
  -H "Api-Key: lk_live_xxx" \
  -d '{"type": "multi", "merchantDriftEnabled": false, ...}'

Use single-use cards for one-off purchases at different merchants
If card was frozen, unfreeze it via POST /v1/cards/{id}/unfreeze

Transaction declined: Card expired or closed

Symptoms:

Transaction fails
Card shows as “closed”

Causes:

Single-use card already used
Card manually closed
Card TTL expired

Solutions:

Single-use cards close after one transaction
Check if card was manually closed
Create a new card for the purchase

Intent shows 'mismatched' after transaction

Symptoms:

Transaction succeeded but intent is “mismatched”
Risk alerts generated

Causes:

Transaction amount differs >10% from declared
Merchant name doesn’t match declared merchantText

Solutions:

This is informational—transaction still completes
Review the mismatch details
Improve future intent declarations:
- Include taxes/shipping in amount estimate
- Use exact merchant strings (check past transactions)

Webhook Issues

Webhooks not being received

Symptoms:

Events occur but no webhooks arrive
Webhook logs show failures

Causes:

Endpoint unreachable
SSL/TLS issues
Firewall blocking
Endpoint returning errors

Solutions:

Verify endpoint is publicly accessible
Check SSL certificate is valid
Ensure endpoint returns 2xx within 30 seconds
Test with dashboard “Send Test” feature
Check your server logs for incoming requests

Webhook signature verification failing

Symptoms:

Webhooks arrive but signature doesn’t match

Causes:

Wrong secret being used
Request body modified by middleware
Encoding issues

Solutions:

Get correct secret from dashboard or API:

curl https://api.ledger.so/v1/webhooks/webhook_xxx/secret \
  -H "Api-Key: lk_live_xxx"

Verify you’re using raw request body (not parsed JSON)
Check your web framework isn’t modifying the body

Receiving duplicate webhook events

Symptoms:

Same event delivered multiple times

Causes:

Normal behavior—webhooks are delivered at-least-once
Your endpoint may have timed out, triggering retry

Solutions:

Implement idempotency using event ID:

const processed = new Set();

function handleWebhook(event) {
  if (processed.has(event.id)) return;
  // Process event...
  processed.add(event.id);
}

Ensure endpoint responds quickly (< 30s)

MCP Issues

MCP tools not appearing in Claude/Cursor

Symptoms:

Connected to MCP server but tools not visible
“No tools available” message

Causes:

Configuration error
Missing or invalid API key
mcp-remote not installed

Solutions:

Verify config file location and syntax:
- Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
- Cursor: .cursor/mcp.json

Check API key is set:

{
  "env": {
    "LEDGER_API_KEY": "lk_live_xxx"
  }
}

Restart the application after config changes
Check MCP server logs for errors

MCP error: 'Agent token required'

Symptoms:

Agent tools fail with authorization error
Admin tools work but agent tools don’t

Causes:

Using agent-only tools without agent context
Missing LEDGER_AGENT_TOKEN or LEDGER_AGENT_ID

Solutions:

For agent-specific operations, provide agent credentials:

{
  "env": {
    "LEDGER_AGENT_TOKEN": "at_live_xxx",
    "LEDGER_AGENT_ID": "agent_xxx"
  }
}

Or use API key which has full access

MCP connection timeout

Symptoms:

Tools take forever or timeout
Intermittent connection failures

Causes:

Network issues
Firewall blocking outbound connections
Proxy configuration needed

Solutions:

Test connectivity:
```
curl https://mcp.ledger.so/health
```
Check firewall allows outbound HTTPS
If behind proxy, configure proxy settings

Funding Issues

Crypto deposit not credited

Symptoms:

Sent USDC/USDT but balance not updated
No deposit.completed webhook

Causes:

Wrong network (sent on unsupported chain)
Wrong token (sent wrong stablecoin)
Transaction still pending

Solutions:

Verify supported networks:

curl https://api.ledger.so/v1/users/user_xxx/funding \
  -H "Api-Key: lk_live_xxx"

Check you sent to correct address on correct network
Verify transaction is confirmed on-chain
Deposits typically credit within 2-5 minutes after confirmation
Contact support with transaction hash if not credited after 30 minutes

Balance shows but 'available' is lower

Symptoms:

Total balance is correct
Available balance is lower than expected

Causes:

Funds held by pending authorizations
Funds allocated to active cards

Solutions:

Check pending transactions
Review active cards and their maxAmount reservations
Available = Total - Pending - CardReservations

Still Need Help?

API Reference

Check the full API documentation

Dashboard

View logs and manage resources

Status Page

Check system status

Support

Contact our team

Getting Started

User Onboarding

Core Concepts

Guides

Troubleshooting

Troubleshooting

Authentication Issues

User & KYC Issues

Card Issues

Transaction Issues

Webhook Issues

MCP Issues

Funding Issues

Still Need Help?

API Reference

Dashboard

Status Page

Support

Getting Started

User Onboarding

Core Concepts

Guides

​Troubleshooting

​Authentication Issues

​User & KYC Issues

​Card Issues

​Transaction Issues

​Webhook Issues

​MCP Issues

​Funding Issues

​Still Need Help?

API Reference

Dashboard

Status Page

Support

Troubleshooting

Authentication Issues

User & KYC Issues

Card Issues

Transaction Issues

Webhook Issues

MCP Issues

Funding Issues

Still Need Help?