Troubleshooting

Start with the check command. It runs the same setup as your app and says what is wrong in plain words:

python -m microauth_fastapi check
python -m microauth_fastapi check --key map_...   # how one key would be treated

The sections below cover what to do when that isn't enough.

The SDK is not connecting

The Connect tab says Waiting for your API to connect until the SDK loads its first snapshot. Run the check from the directory your app runs in, then match the result:

What the check says	What to do
MICROAUTH_SECRET_KEY is missing or is not an SDK secret	Set the secret in the environment or a .env file. It starts with mas_, and you can reveal it on the Connect tab. A map_ key belongs to a customer and won't work here
MicroAuth rejected this secret	The secret was rotated or belongs to another API. Copy the current one from the Connect tab
snapshot request failed with a connection error	The machine can't reach https://api.microauth.com. Allow outbound HTTPS, or check your proxy settings
this machine's clock is ... MicroAuth's	Turn on time sync (NTP) on the machine. The SDK reports usage on MicroAuth's clock either way, so nothing is billed in the wrong hour
the journal is in the temp directory	Set MICROAUTH_JOURNAL_DIR to a directory that survives a reboot, or to a mounted volume in a container
Everything passes, but the dashboard still waits	The check ran against another server. Unset MICROAUTH_BASE_URL unless you were told to set it

The tab turns green within a few seconds of a successful check. Later on, Your SDK went quiet means MicroAuth hasn't heard from your API for 10 minutes: the app stopped, or it lost its connection to MicroAuth.

Requests aren't being counted

The Connect tab says Make a test request until the first usage report arrives, about five seconds after a request.

• Make sure the route has customer: Customer = Security(auth). Routes without it aren't metered.
• Send the key in the header the SDK reads. That is X-API-Key unless you changed Key header on the Portal tab, in which case pass the same name: MicroAuth(app, header_name="X-Weather-Key").
• Use the test key from the Connect tab, or a key from this API's portal. Keys from another API get 401.
• Keep the app running for a few seconds after the request so the report can go out. On serverless platforms, see serverless.

What each error means

These are the responses your customers get from your API when a check fails.

Status	Body detail	Why	Fix
401	Invalid or missing API key	No key, a revoked key, or a key from another API	Create a key on the portal
402	Insufficient credit balance	The balance can't cover one billable request	Top up on the portal, or add credit from the customer's page
403	This account is suspended	You suspended the customer	Reactivate them on the Customers tab
403	This account is waiting for approval	Sign ups need your approval and this customer is still waiting	Approve them on the Customers tab
429	Rate limit exceeded	Above the customer's requests a second. Retry-After says when to retry	Raise the limit on the plan or with custom limits
429	Monthly request quota exceeded	The customer's monthly quota is used up	Raise or remove the quota
429	Platform monthly request allowance exhausted	Your MicroAuth plan's allowance is used up for this month	Upgrade the plan
503	Authorization is temporarily unavailable	The SDK secret was rotated and the old one expired, MicroAuth suspended the API, or the SDK couldn't get trustworthy data from MicroAuth or Redis	Deploy the current secret, then check that your server can reach MicroAuth and Redis. If the check says the API is suspended, contact support

A customer still gets 402 after adding credit

The SDK picks up balances on its next snapshot, every 30 seconds by default. Card payments are applied as soon as Stripe confirms them, usually within seconds. The Payments tab and the customer's balance history show when the credit arrived.

MicroAuth refused some usage

The SDK logs a line like this when MicroAuth refuses usage for good:

microauth: MicroAuth refused usage item c41d9e7b-... (3 request(s) with status 200): api_key_id is not a key of this API

Refused usage is never charged, and the SDK keeps it so you can look at it later. python -m microauth_fastapi usage lists it with the reason. The usual causes:

• The customer was deleted before the usage reached MicroAuth, which removes their keys too. There is nobody left to bill, so nothing needs fixing. Revoking a key doesn't cause this: usage from before the revocation is still recorded.
• The usage is older than 45 days, for example from a server that was offline for weeks. MicroAuth doesn't accept usage that old.
• idempotency_key was already used for a different request means two processes sent different versions of the same item. That can happen when a journal directory is copied to another server while both keep running. Give every server its own MICROAUTH_JOURNAL_DIR, or use Redis.

Charges don't match what the SDK expected

Every request is charged under the usage policy it was admitted with, which fixes the price, the billing model and the billable status codes. The SDK and MicroAuth should therefore always agree, and a log line that starts with microauth: MicroAuth charged ... but the SDK expected points at a bug. Email support@microauth.com with that line and the output of python -m microauth_fastapi usage --json.

Limits are higher than configured

Without Redis, each worker process counts on its own, so four workers allow about four times the rate limit. Add Redis to share the counters across workers and machines.

Redis runs out of connections

The SDK keeps up to 64 Redis connections per process by default. With many workers on a small Redis plan, lower it with MicroAuth(app, redis_max_connections=10). See Redis connections under load.

New customers can't sign up

• If the portal says it can't take new sign ups, the API reached its plan's customer limit. Upgrade, or delete customers you no longer need.
• With the Invite only sign up mode, people need an invite from the Customers tab. See sign up modes.

The custom domain isn't working

Check the records against the custom domain steps. The most common cause is a proxied, orange cloud record in Cloudflare. Set it to DNS only and click Check now.

Sign in codes aren't arriving

Codes come from no-reply@microauth.com. Check spam and any filter for automated mail, then ask for a new code. If your company blocks outside senders, ask IT to allow that address.

Still stuck?

Email support@microauth.com with the output of the check command. It never prints full keys, so it is safe to paste.