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

Event ingestion failures

400 on POST /v1/ingest/meter-data

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