For developers

Troubleshooting

Common errors during integration and how to resolve them. For full error code documentation, see Errors.

Authentication errors

401 Unauthorized

  • You’re using a test key against api.solvimon.com, or a live key against test.api.solvimon.com. Keys are environment-bound — test keys only work on the test endpoint.
  • The X-API-KEY header is missing or misspelled.
  • The key has been revoked. Generate a new one under Settings → API keys.

Resource not found

404 Not Found / RESOURCE_NOT_FOUND

  • You’re querying by reference but the value doesn’t match exactly (case-sensitive).
  • The resource is in DRAFT status and isn’t visible to some query endpoints. Activate it first.
  • You’re using a test environment ID against the production endpoint or vice versa. IDs are environment-specific.

When filtering by reference, use the query parameter form:

$curl "https://test.api.solvimon.com/v1/customers?reference=superstore-001" \
>  -H "X-API-KEY: <apiKey>"

Subscription creation failures

Errors on POST /v1/pricing-plan-subscriptions/init

SymptomLikely causeFix
RESOURCE_NOT_FOUND on pricing planPricing plan reference is wrong or the plan is in DRAFTActivate the pricing plan version first
Error on customerCustomer status is DRAFTPOST /v1/customers/<ref>/activate
Missing billing entitybilling_entity_reference not setConfigure a billing entity under Settings → Billing entities; it’s required before invoices can be generated
UNABLE_TO_PROCESS_INSTRUCTIONSOne or more pricing plan items are misconfiguredCheck that all product items on the plan are ACTIVE

Event ingestion failures

400 on POST /v1/ingest/meter-data

SymptomLikely causeFix
RESOURCE_NOT_FOUND for metermeter_reference doesn’t match an existing meterCheck the reference is exact and the meter is ACTIVE
Missing required propertyA meter property marked ACTIVE is required but not includedInclude all active meter properties in meter_properties
Duplicate referenceYou already sent an event with this referenceThis is correct behavior — Solvimon deduplicates on reference. If you need to send a new event, use a new unique reference.
Customer not foundcustomer_reference doesn’t match an active customerConfirm the customer exists and is ACTIVE

Event accepted but not appearing on the invoice

  • The event timestamp is outside the current billing period. Events are matched to the period their timestamp falls in.
  • The meter linked to the subscription’s product item doesn’t match the meter_reference on the event. Verify the product item’s meter value calculation references the correct meter.

Invoice stuck in DRAFT

After a billing period ends, Solvimon moves draft invoices to FINAL after a grace period (typically 8 hours). If an invoice appears to be stuck:

  • Check on_hold status on the invoice — a hold indicates a configuration issue preventing finalization (e.g., missing tax information).
  • For testing, you can manually advance an invoice in Desk under Invoicing → Invoices → select the invoice → Finalize.

Webhook delivery failures

Webhooks not arriving

  • Your endpoint is returning a non-2XX status or timing out (10 second limit). Check your server logs.
  • ngrok tunnel has expired during local development. Restart ngrok and update the webhook URL.

Events arriving out of order or with delays

When a webhook delivery fails (non-2XX or timeout), Solvimon queues subsequent events until the failed one is retried and acknowledged. A single failing webhook can back up all events for that endpoint. Fix the underlying delivery issue to clear the queue.

See Webhooks for the retry schedule and signature verification.

Getting help

When contacting support, include:

  1. The X-REQUEST-ID header value from the failing response — this is the fastest way for Solvimon to find the request in logs
  2. The endpoint you called and the HTTP method
  3. Your request body (redact the API key)
  4. The timestamp of the request
  5. The environment (test or production)

You can find the X-REQUEST-ID in the response headers:

$curl -v https://test.api.solvimon.com/v1/customers \
>  -H "X-API-KEY: <apiKey>" 2>&1 | grep x-request-id