Supafone Labs ยท Documentation
Documentation menu

Troubleshooting#

401 or Invalid Key#

One sl_live_... key authenticates both APIs โ€” https://api.labs.supafone.ai and https://api.supafone.ai. If you get a 401:

Legacy scoped sf_live_... keys authenticate only the hosted-agent surface (https://api.supafone.ai/api/v1/labs), not Labs Cloud Supervisor/TTS/STT.

402 Managed Minutes Exhausted#

The account-wide managed-runtime ledger cannot reserve another call. The first five minutes belong to the account, so creating another key, agent, browser session, or CLI process does not create another allowance. Calls already starting or in progress may also hold active_reserved_seconds.

bash
curl https://api.labs.supafone.ai/v1/billing/balance \
  -H "Authorization: Bearer $SUPAFONE_LABS_API_KEY"

Read the structured response's detail.code. For managed_minutes_exhausted, use its checkout_endpoint to create a Stripe Checkout Session, open checkout_url, poll the Checkout status, and retry only after payment is confirmed. See Pricing and Credits.

403 Admin Secret Required#

Admin endpoints require:

text
X-Admin-Secret: <server-side-admin-secret>

Do not call admin endpoints from public browser clients.

429 Daily Cap Reached#

Plans have request-count abuse caps on top of the minute balance. Check:

bash
curl https://api.labs.supafone.ai/v1/usage \
  -H "Authorization: Bearer $SUPAFONE_LABS_API_KEY"

503 Upstream Provider Not Configured#

The gateway is missing the vendor key for the requested feature. Examples:

Hosted Agent Created But No Number#

Check whether you used create() instead of createInboundWithNumber() or createOutboundWithNumber(). Creating an agent and buying/assigning a number are separate operations unless you use the helper.

Accidental Paid Number Risk#

Default to:

json
{ "number_strategy": "default_pool" }

Only use dedicated or premium after explicit user confirmation. Premium numbers are $3/month.

No Matching Number#

Broaden the search:

json
{
  "country_code": "US",
  "area_code": "415",
  "limit": 10
}

If the pool has no match, ask the user whether to search a nearby area code, reserve a dedicated number, or bring their own carrier.

Builder or QA Returns "Log In First"#

Builder and QA run under a console session:

ts
await supafone.login(process.env.SM_EMAIL!, process.env.SM_PASSWORD!);

API-key-only auth is enough for usage, logs, Supervisor, TTS, STT, nudges, metrics, and hosted-agent methods, but not for session-scoped builder flows.

WebSocket Live STT Fails in Node#

Node versions without a global WebSocket need an implementation:

ts
import WebSocket from "ws";

supafone.liveTranscribe({ WebSocketImpl: WebSocket });

Browsers cannot set WebSocket headers, so the SDK sends the Labs key as an api_key query parameter.

Supervisor Is Silent#

Silence is valid when no correction is needed. If silence is unexpected, check:

View raw Markdown