API best practices: keys, errors and rate limits
API best practices for the Trillet REST API: keep API keys secure, handle errors and retries, stay within the outbound call limits, and check your setup before production.
These API best practices cover how to call the Trillet REST API safely and reliably: keeping API keys secure, handling errors, staying within rate limits and checking your integration before you go to production.
Authentication
API Keys
- Keep your API keys secure and never expose them in client-side code
- An API key acts as the user who created it, with that user's role, in every workspace that user belongs to. Create keys from a dedicated user whose role has only the permissions your integration needs
- Use different API keys for development and production
- Rotate your API keys periodically
- Send the key in the
x-api-keyheader, with the workspace inx-workspace-id
Error Handling
Errors come back as flat JSON objects, not a nested error object. Check the HTTP status first, then read code when it is present, and fall back to message or error. Don't parse the text. See API introduction for the status codes.
curl -X POST https://api.trillet.ai/v1/api/call \
-H "x-api-key: YOUR_API_KEY" \
-H "x-workspace-id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"call_agent_id": "a5a5a5a5a5a5a5a5a5a5a5a5",
"to": "+14155550123"
}'
An empty wallet (400):
{
"error": "Insufficient funds",
"code": "INSUFFICIENT_FUNDS",
"message": "Your workspace balance is $0.00. Please add funds to continue.",
"balance": 0,
"walletScope": "workspace"
}
An invalid phone number (400):
{
"status": "error",
"message": "to must be a valid phone number in E.164 format, e.g. +14155550123",
"code": "INVALID_PHONE_NUMBER"
}
An agent with no live call flow (422):
{
"status": "error",
"message": "Failed to initiate call",
"error": "This agent has no live call flow, so the call can't run. Use an agent whose call flow is live, or create one in the portal.",
"code": "NO_ACTIVE_CALL_FLOW"
}
Initiate Outbound Call lists every code that endpoint returns.
Rate Limits
There is no general per-key request quota. What is enforced:
- Outbound calls (Initiate Outbound Call) are limited per workspace in a 60-second window: 1 call per minute without a paid plan or wallet top-up, 20 per minute on Studio or Agency Plus or after a top-up, and no limit on Enterprise pricing. Calls placed by a batch use a separate allowance. Over the limit, the call is rejected with
error"Rate limit exceeded: ... Please wait S seconds before making another call." Wait that many seconds before retrying. - A few other endpoints, such as voice previews and the public web call endpoints, have their own limits and answer
429when you exceed them.
Retry with backoff on 429 and on 5xx responses. Don't retry 4xx responses unchanged: fix the request first.
Production Checklist
-
Authentication
- Use production API keys from a dedicated, least-privilege user
- Implement key rotation
- Secure key storage
-
Error Handling
- Branch on HTTP status and
code, not on message text - Retry with backoff on
429and5xx, and honour the wait in the outbound call rate-limit message - Log errors appropriately
- Branch on HTTP status and
-
Monitoring
- Track API response times
- Monitor error rates
- Set up alerts
Need Help?
Last updated on