Troubleshooting hub

Most integration problems fall into a handful of shapes, and each has a fast check. Find your symptom below, run the check, and follow the link for the full write-up.

What symptom are you seeing?

Symptom	Most likely cause	Check
`401 Unauthorized` on every request	Missing or expired key, or a key from the other region	Run the auth check below against both base URLs
`403 Forbidden` on some requests	The key’s role lacks the permission	API key roles
`404` on every request	Base URL is missing `/v1` or has a trailing slash	Compare against `https://us.api.flexprice.io/v1`
`404` on one object	Wrong ID, or the object lives in another environment	Keys are bound to one environment; sandbox IDs are invisible to a production key
`400` with a validation message	A required field is missing or an enum value is wrong	Read `error.message`; it names the field. Error responses
`409 Conflict`	Two writes raced, or the object already exists	Retry the read, or look the object up. Safe to retry
`429 Too Many Requests`	Rate limit	Back off with jitter; batch events with `POST /events/bulk`
Event returns `202` but never shows up	`event_name` does not match a feature exactly, or `external_customer_id` matches no customer	Usage events not showing up, and subscribe to `event.rejected`
Usage number is wrong	Aggregation field name or type mismatch	Wrong aggregation values
Usage shows but the invoice has no charge	Feature is not priced in the plan, or the customer has no subscription	No charges in billing
Webhook never arrives	Endpoint not subscribed to that event, or registered in the other environment	Dashboard Webhooks > Logs; Set up an endpoint
Webhook arrives, signature check fails	Handler verifies a re-serialized body instead of the raw bytes	Signature verification
Webhook delivered more than once	At-least-once delivery	Dedupe on `svix-id`; Retries and ordering
CLI says `command not found`	Install directory not on `PATH`	CLI install
CLI exits `3`	Authentication failure	`flexprice whoami`; CLI authentication
MCP server does not appear in the client	Config not saved, or the client was not restarted	MCP troubleshooting
UI component renders unstyled	Stylesheet not imported, or theme variables set on an ancestor	Install the UI kit

The auth check, with your key in $KEY:

curl -s -X POST "https://us.api.flexprice.io/v1/customers/search" \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" -d '{}'

A 200 with an items array means the key and region match. Swap in https://api.cloud.flexprice.io/v1 if you get 401.

Tools that show what happened

Event Debugger

Every ingested event with how it matched a feature and aggregated. The first stop for any metering question.

Webhook logs

Each delivery attempt, the response your endpoint returned, and a replay button.

CLI with --debug

Dumps the exact request and response with secrets redacted. Fastest way to see what the API actually received.

Ingestion monitoring

Throughput and rejection counts over time, to tell a code bug from a traffic change.

Run a five-minute diagnostic

Confirm the key and region

flexprice whoami

Or send any request with --debug. A 401 here ends the investigation: the key is wrong for this region or environment.

Confirm the object exists where you think

flexprice customers by-external-id "$EXTERNAL_ID" --output json

Exit code 4 means the customer is not in this environment.

Send one event and watch it

flexprice events ingest --event_name="$NAME" --external_customer_id="$EXTERNAL_ID" --output json

Open the Event Debugger and find it. If it is there but unmatched, the event name or customer is wrong. If it is matched but the number is off, the aggregation property is wrong.

Check the invoice preview

flexprice invoices preview --subscription_id="$SUB_ID" --output json

This shows what the next invoice would charge right now. A missing line item means the feature is not priced in the plan.

Deeper troubleshooting guides

Usage events troubleshooting: the long version of every metering problem
Validating events: what the ingest endpoint checks and what it does not
Error responses: every status code and the error body shape
API key troubleshooting: keys that stopped working, lost keys, and role errors
MCP server troubleshooting: connection, URL, and Docker problems
Self-hosting troubleshooting: containers, migrations, and Kafka

Still stuck?

Bring the request ID or the svix-id, the environment, the region, and the exact time to support@flexprice.io or the community Slack. Check the status page first if every request is failing at once.

​What symptom are you seeing?

​Tools that show what happened