Troubleshooting

Start with the HTTP status, error.code, endpoint, and trace identifier. Most Northsun (formerly Mnemix) integration failures fall into authentication, phone normalization, request-shape drift, rate limiting, or platform webhook mapping.

Symptom	Likely cause	Fix
401 unauthorized	Missing bearer prefix, wrong key prefix, unknown/revoked key, or secret not loaded in the runtime	Verify the server-side environment and authentication format.
404 not_found on caller lookup	The key is valid, but the tenant has never seen that phone number	Use recall_and_enrich to begin the caller lifecycle, or render an empty state.
400 Invalid phone number	Phone number is not normalizable	Send E.164, such as +15551234567; encode + as %2B in URL paths.
422 validation_error	Field name, enum, transcript turn, or required value differs from the route schema	Compare the request with the API reference.
429 rate_limited	Tenant request bucket is exhausted	Read the rate headers, wait with jitter, and reduce duplicate/concurrent calls.
503 service_unavailable during auth	A cold key could not be authenticated while the backing dependency was unavailable	Retry with capped backoff; do not rotate the key automatically.
Caller returns but enrichment fields are null	Enrichment is partial, unavailable, or did not finish inside the recall deadline	Continue with memory/caller data; do not block the conversation on enrichment.
calls/end returns 204 with no JSON	The interaction is already committed durably by the time 204 returns — see Hangup, and what happens next	Do not call .json(). Retain the trace for troubleshooting.
Repeat calls do not show expected history	The end-of-call webhook did not fire, or mapped the wrong number/session	Log the webhook event, confirm the 204, and re-check session_id/phone_number normalization. Escalate if the later recall never changes.
Recall returns history, but not the item you expected	Caller memory comes back in recency order — most recently updated first — not ranked by relevance to the current call	Do the selection in your application; do not expect a relevance ranking from this endpoint. See Salience.
MCP client cannot connect	Wrong URL, missing HTTP transport, or missing authorization header	Use https://mcp.mnemix.ai/mcp and inspect MCP setup.

Platform webhook checklist

1. Confirm the platform event really reaches your server.
2. Log the platform call identifier and event type, never the API key.
3. Normalize the caller number before calling Northsun.
4. Use the same session_id on recall and write-back.
5. Map transcript roles to user or agent and provide numeric ts_ms values.
6. Map unsupported outcomes to other instead of inventing a new enum value.
7. Deduplicate platform retries before calling calls/end again.

Collect a safe diagnostic receipt

Record:

• UTC timestamp and deployment version.
• Northsun endpoint and HTTP method.
• HTTP status and error.code.
• X-Trace-Id and rate-limit headers.
• Platform event type and redacted call identifier.
• Whether the failure reproduces with a minimal request.

Do not record raw API keys, full transcripts, or unredacted personal data.

Next steps

• Errors and retries — retry classification.
• Production readiness — prevent common launch failures.
• API reference — validate fields and enums.