Use this page when a request behaves differently from the happy path. For the complete response codes, see Errors and response format.
Credentials and requests
Do I need a JWT or an API key?
Use a JWT for account operations such as profile, workspaces, API-key management, billing history, and activity. Use an ngm_... API key for model discovery and gateway calls including chat, embeddings, transcription, speech, and combined voice. See Authentication for the complete matrix.
Why did my chat completion response not use the usual Ngamia envelope?
POST /v1/chat/completions intentionally mirrors OpenAI’s response and error shape. POST /v1/embeddings and the transcription route also return OpenAI-compatible JSON. Speech returns raw audio on success, while the combined voice route returns JSON with optional base64 audio. See Errors and response format.
What does the model field accept?
Use the public model value returned by Models, such as openai/gpt-4o-mini. Do not use the catalog resource id in a gateway request, and do not construct a value from private provider details.
Can I use OpenAI SDKs with Ngamia?
Yes. Set base_url to https://api.ngamia.cc/v1 and use an Ngamia API key. The Quickstart includes curl, Python, and Node examples.
Billing and retries
When am I charged?
Ngamia checks the available balance before the request. Chat and embedding requests settle from completed usage; voice stages reserve an estimate and then settle or release it as the stage completes or fails. Inspect usage in Activity and the balance or ledger in Billing.
My request failed with 402 insufficient_quota or insufficient_credits. What now?
The account does not have enough credits for the requested operation. Top up through POST /v1/payments/topup, wait for the payment to complete, then retry the original request. Do not treat a 402 as a transient network failure.
Why is my top-up still pending?
Mobile-money payments are asynchronous. Keep the Ngamia payment id, poll the payment status, and wait for confirmation. Do not create duplicate top-ups while the first payment is still pending. See Payments.
Can I retry without double-charging?
Use a unique Idempotency-Key for a logical top-up, chat, or embedding request. Do not blindly replay raw-audio speech or combined voice calls unless your deployment explicitly documents replay behavior. See Idempotency.
What should I do after a 429 response?
Wait, then retry with exponential backoff and jitter. Do not start an unbounded retry loop. API-key traffic is rate limited by key id; using one key per server integration makes limits easier to reason about. See Rate limits.
Accounts and workspaces
Can multiple people share a workspace?
Workspaces are account resources. Use the workspace endpoints to create, read, update, and delete workspaces, then apply the permissions supported by your account model. Keep workspace management behind your server or authenticated dashboard session.
I am getting 404 for a resource I know exists. Why?
Ngamia may return 404 not_found when a resource does not exist or does not belong to the authenticated account. Check the resource id, the active account, and the credential type. This behavior avoids exposing another account’s resources.
Testing and browser security
Is there a sandbox or test mode?
Ngamia’s local development base URL is http://localhost:8080/v1. Use your local environment and test credentials when running the API locally. For production testing, keep requests small and monitor the balance.
How do I use embeddings or Ongea na Ngamia?
Use Embeddings for vector search and retrieval. Use Voice & Ongea na Ngamia for Kiswahili transcription, localized text, and optional audio. Discover compatible models from the live catalog instead of hardcoding model names.
Can I call the API directly from browser JavaScript?
Do not put an ngm_... API key in browser JavaScript. Anyone who can inspect the browser can copy it. Send requests through your server, where the key can remain in an environment variable or secret manager.
Where do I report an issue?
Include the endpoint, HTTP status, error_code, and request_id in a support report. Never include the API key, password, refresh token, or full authorization header.