Keys
Create one API key per environment and service, each with acredit_limit, see API keys. A runaway loop then stops at the key’s limit instead of draining the whole balance. You can also revoke one service’s key without touching the others.
Keep keys in server-side secrets. A key in browser or mobile code can be read by anyone who opens the app.
Balance
Set a low balance alert on the Credits page, above a day of spend. You then have time to top up before requests start failing with402.
Keep enough balance for your peak concurrency. Each running paid request reserves 0.05 credits, so a balance of $5 runs at most 100 paid requests at once, see Limits.
Models
Copy model ids from the catalog and check theparameters of their operation and their input_modalities. NagaAI drops a parameter the serving provider doesn’t support without an error, so a setting your app depends on can silently have no effect.
Pick a fallback model for your main one and switch to it when a request fails with 503. NagaAI already retries across the providers of the same model, but it doesn’t switch models for you, see Routing.
Requests
Set a client timeout that fits your longest answers, because long reasoning requests can run for minutes. NagaAI still finishes and charges a request your client gave up on. For Responses, send the full conversation in every call, because NagaAI keeps no state between requests. See Conversation state. Choose a routing strategy if latency or cache hits matter to you.Errors
Retry408, 429 and 503 with backoff, and wait for Retry-After when the response carries it, see Errors.
Make stream handlers expect an error event after content has started. At that point the status is already 200, see Errors in a stream.
Log the x-request-id header of every response. Support uses it to find the request.