Errors and rate limits
Every error has the same shape: a fixed code your program can check, and a message in plain words you can show to a person.
What an error looks like
The HTTP status tells you the kind of problem. The body says exactly what happened:
{
"error": {
"code": "insufficient_scope",
"message": "This API key can't do that. It needs the calls:write scope."
}
}A 422 also lists the fields that need fixing, by name:
{
"error": {
"code": "invalid_request",
"message": "Some fields are missing or not valid.",
"fields": {
"recording_url": "Field required"
}
}
}Check the code, not the message. We may reword messages to make them clearer; codes don’t change.
Error codes
| Status | Code | What it means | What to do |
|---|---|---|---|
| 401 | unauthorized | The key is missing, mistyped, revoked or expired. | Check the header and the key. Create a new key if it was revoked. |
| 402 | credits_exhausted | The workspace has no credits left for this. | Top up or wait for the next billing cycle. Reading data still works. |
| 402 | plan_inactive | The workspace has no active plan. | Choose a plan in Settings → Billing. |
| 403 | insufficient_scope | The key works, but it doesn’t have the scope this route needs. | Create a key with a preset that includes the scope named in the message. |
| 403 | account_suspended | The account is suspended. | Email us to find out why and what to do. |
| 404 | not_found | Nothing with that id exists in this key’s workspace. | Check the id. A key only sees its own workspace. |
| 409 | conflict | The request clashes with the current state, for example analyzing a call that has already been analyzed. | Read the message. Usually there’s nothing to do. |
| 422 | invalid_request | A field is missing or not valid. fields says which, and why. | Fix the fields listed, then send the request again. |
| 429 | rate_limited | Too many requests in a minute. | Wait the number of seconds in the Retry-After header, then try again. |
| 502 | ai_failed | The AI step failed, so nothing was charged. | Try again in a minute. |
| 503 | unavailable | This part of the service is down for a moment. | Try again after a short wait. |
| Other 5xx | Any | Something went wrong on our side. | Try again in a minute. If it keeps happening, email us with the time and the route. |
Rate limits
Limits are counted per key, per minute:
- 120 requests a minute in total.
- Of those, 20 a minute for the routes that start AI work:
POST /ask,POST /callsandPOST /calls/{id}/analyze.
Over the limit, you get a 429 with a Retry-After header: the number of seconds to wait. Many requests with a wrong key from one address are refused for a minute too. Need more? Email hello@listenfox.com and tell us what you’re building.
Retrying safely
- Retry a 429 after
Retry-After, and a 5xx answer or a timeout after a short wait that grows each time (for example 1, 2, then 4 seconds). - Don’t retry a 401, 403, 404, 409 or 422 unchanged. The same request will fail the same way.
- Reads are always safe to repeat. To add calls safely, send your own
external_idwithPOST /calls: if the same id arrives twice, you get the first call back and nothing is charged again. - Completing a follow-up that’s already done changes nothing, so that’s safe to repeat too. See the API reference for each route.