Meter Troubleshooting

Quick fixes for common Solenoid Meter issues.

Error Lookup

Balance deduction failing

Symptoms: insufficient_balance error (402), deduction succeeds but balance unchanged, or unexpected negative balance.

Diagnosis:

curl https://api.solenoid.systems/v1/meter/{meterId}/balance \
  -H "Authorization: Bearer $API_KEY"

Resolution:

• Balance is zero: Refill the meter with POST /v1/meter/:meterId/refill.
• Wrong meter: Verify the meter ID matches the intended user.
• Duplicate request: The first request may have succeeded. Check the current balance before retrying.

Prevention: Call deduct directly and handle the 402 response. Do not check-then-deduct — the atomic deduct call prevents race conditions.

Refill not adding credits

Symptoms: Refill operation succeeds but balance is unchanged, or balance_overflow error.

Diagnosis:

curl https://api.solenoid.systems/v1/meter/{meterId}/balance \
  -H "Authorization: Bearer $API_KEY"

Resolution:

• Balance overflow: The max balance is 2^53 - 1. Reset the meter with POST /v1/meter/:meterId/reset before refilling.
• Zero or negative amount: The amount field must be a positive integer.
• Wrong meter ID: Verify the meter ID in the request URL.

Meter not found

Symptoms: meter.meter_not_found error (404), or meter existed previously but now returns 404.

Resolution:

• Typo in meter ID: Multi-tenant meter IDs are case-sensitive. Double-check the value.
• Wrong API key: Different keys belong to different accounts. Verify with GET /v1/meter/balance.
• Meter never created: Multi-tenant meters are created implicitly on first refill or reset. A balance or deduct call to a nonexistent meter returns 404.

Prevention: Use a consistent naming convention for meter IDs (e.g., user-{userId}) and store them in your database.

Usage tracking drift

Symptoms: Balance does not match expected usage, or duplicate/missing deductions.

Resolution:

• Duplicate deductions: Likely caused by network retries without idempotency. Check the current balance and reconcile.
• Failed operations not refunded: If a downstream operation fails after deduction, refill the deducted amount.
• Floating point amounts: Meter uses integer balances. Store cents, not dollars, to avoid rounding errors.

Prevention: Log all meter operations with unique IDs and reconcile periodically.

Concurrent operation conflicts

Symptoms: Balance inconsistencies under high load, or operations succeeding when balance should be zero.

Resolution: Trust Meter’s atomic deduct operation. It will return 402 if the balance is insufficient, regardless of concurrency.

// Correct: atomic deduct-or-fail
const res = await fetch(`/v1/meter/${meterId}/deduct`, {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ amount }),
});
if (res.status === 402) {
  // Handle insufficient balance
}

Prevention: Never check balance then deduct in two separate calls. Use the single atomic deduct call.

Rate limiting

Symptoms: 429 Too Many Requests errors, especially during high-volume operations.

Diagnosis:

curl -I https://api.solenoid.systems/v1/meter/{meterId}/balance \
  -H "Authorization: Bearer $API_KEY"
# Check X-RateLimit-Remaining header

Resolution:

• Batch operations: Buffer usage events locally and flush every 1-60 seconds instead of calling the API per event.
• Exponential backoff: On 429, wait and retry with increasing delays.
• Reduce polling: Cache balance values locally instead of checking on every request.

See Rate Limits for per-tier limits.