> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Troubleshooting

Common errors during integration and how to resolve them. For full error code documentation, see [Errors](/platform-guides/for-developers/api).

---

## 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 Developers → 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:

```bash
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](https://docs.solvimon.com/api-docs/configuration-api/pricing-plan-subscriptions/post-pricing-plan-subscriptions-init)**

| Symptom                              | Likely cause                                              | Fix                                                                                                          |
| ------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `RESOURCE_NOT_FOUND` on pricing plan | Pricing plan reference is wrong or the plan is in `DRAFT` | Activate the pricing plan version first                                                                      |
| Error on customer                    | Customer status is `DRAFT`                                | `POST /v1/customers/<ref>/activate`                                                                          |
| Missing billing entity               | `billing_entity_reference` not set                        | Configure a billing entity under Settings → Billing entities; it's required before invoices can be generated |
| `UNABLE_TO_PROCESS_INSTRUCTIONS`     | One or more pricing plan items are misconfigured          | Check that all product items on the plan are `ACTIVE`                                                        |

---

## Event ingestion failures

**`400` on [POST /v1/ingest/meter-data](https://docs.solvimon.com/api-docs/event-api/ingest/post-ingest-meter-data)**

| Symptom                        | Likely cause                                                  | Fix                                                                                                                           |
| ------------------------------ | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `RESOURCE_NOT_FOUND` for meter | `meter_reference` doesn't match an existing meter             | Check the reference is exact and the meter is `ACTIVE`                                                                        |
| Missing required property      | A meter property marked `ACTIVE` is required but not included | Include all active meter properties in `meter_properties`                                                                     |
| Duplicate `reference`          | You already sent an event with this reference                 | This is correct behavior — Solvimon deduplicates on `reference`. If you need to send a new event, use a new unique reference. |
| Customer not found             | `customer_reference` doesn't match an active customer         | Confirm the customer exists and is `ACTIVE`                                                                                   |

**Event accepted but not appearing on the invoice**

* Check `processed_details.not_matched.variant` on the event: it says why the event was not billed. See [Unbilled usage](/platform-guides/meter-and-event-design/unmatched-events).
* 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](/platform-guides/for-developers/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:

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