Meter Errors

Solenoid Meter returns structured JSON errors with machine-readable codes and human-readable messages.

See Error Format for the shared error schema.

Error Code Reference

Code	HTTP	Cause	Fix
`validation_error`	400	Invalid request body or parameters	Check the `fields` object for specific failures (negative amounts, missing fields)
`unauthorized`	401	Missing or invalid API key	Add a valid `Authorization: Bearer sm_xxx` header
`forbidden`	403	Authenticated but not authorized for this meter	Verify you own the meter and your key has the required scopes
`not_found`	404	Meter does not exist or invalid route	Verify the meter ID; multi-tenant meters are created on first use
`meter.insufficient_balance`	402	Balance too low for the requested deduction	Refill the meter or reduce the deduction amount
`meter.balance_overflow`	400	Refill would exceed the max balance (2^53 - 1)	Reset the meter or split across multiple meters
`rate_limit_exceeded`	429	Too many requests in the current window	Back off with exponential retry; consider batching operations

Handling Key Errors

Insufficient balance (402): Surface this to end users and prompt for a top-up. Check balance with GET /v1/meter/:meterId/balance before expensive operations.

Rate limiting (429): Batch high-frequency operations. Buffer usage locally and flush every 1-60 seconds. Use exponential backoff on retries.

Balance overflow (400): The max balance is 2^53 - 1 (JavaScript safe integer). If you approach this limit, use multiple meters for different resources or reset the meter periodically.

Best Practices

Use integers for all amounts. If you need cents, store as cents (not dollars) to avoid rounding drift.
Trust atomic operations. Do not check-then-deduct. Call deduct directly and handle insufficient_balance on failure.
Batch high-volume events. Accumulate usage locally and flush to Meter periodically to reduce API calls.
Log request IDs. Every response includes X-Request-Id for debugging with Solenoid support.

For step-by-step debugging, see Troubleshooting.