Developer docs: Errors and limits

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:

403 Forbidden
{
  "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:

422 Unprocessable Content
{
  "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

StatusCodeWhat it meansWhat to do
401unauthorizedThe key is missing, mistyped, revoked or expired.Check the header and the key. Create a new key if it was revoked.
402credits_exhaustedThe workspace has no credits left for this.Top up or wait for the next billing cycle. Reading data still works.
402plan_inactiveThe workspace has no active plan.Choose a plan in Settings → Billing.
403insufficient_scopeThe 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.
403account_suspendedThe account is suspended.Email us to find out why and what to do.
404not_foundNothing with that id exists in this key’s workspace.Check the id. A key only sees its own workspace.
409conflictThe 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.
422invalid_requestA field is missing or not valid. fields says which, and why.Fix the fields listed, then send the request again.
429rate_limitedToo many requests in a minute.Wait the number of seconds in the Retry-After header, then try again.
502ai_failedThe AI step failed, so nothing was charged.Try again in a minute.
503unavailableThis part of the service is down for a moment.Try again after a short wait.
Other 5xxAnySomething 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 /calls and POST /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_id with POST /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.