Errors

When a request cannot be handled, the API responds with an HTTP error status and a JSON body with this shape:

{
  "error": {
    "code": "file_too_large",
    "message": "The recording is larger than the plan allows."
  }
}

Write your code against code, not against message. The codes are stable. The messages are in English, are meant to be read by a person, and their wording can change.

The request is wrong and will still be wrong if you repeat it unchanged. Do not retry it: fix what you send.

• bad_request has two causes. The first is sending the file as the body of the request instead of inside a form. The second is a request of 20 MB or more: that is the limit of the API, and above it the form is never read. If the error only appears with long recordings, this is the cause, and the fix is to compress the audio.
• no_file means the form arrived correctly but without a file. The field has to be named exactly file.
• empty_file is a file of zero bytes. If you get it, check that your system is not sending the recording before it has finished writing it to disk.
• not_audio means the file does not declare an audio/… type and its name does not end in an audio extension. Check how your system names the file inside the form.
• file_too_large means the file fits in a request but is larger than the per-file maximum of your plan. The fix is to compress the audio: for speech, mono MP3 at 64 kbps is enough.

Every call belongs to an agent in Team. Retrying the same request does not help.

• agent_required: send agent_code or agent_name, or have the file name carry the agent’s code.
• unknown_agent: add the agent in Team, with the same code your telephony system uses, and send the recording again. If the team already takes every seat of the plan, a free seat is needed first.

Check that the header is Authorization: Bearer ck_…, with a space after Bearer and no quotes or line breaks around the key. If the header is correct, someone may have revoked the key: look at the list in Integrations. Do not retry with the same key.

The request is correct, but the account cannot accept more for now. Retrying right away does not help.

• no_minutes clears on its own when the next period starts, or when the limits of the account are raised.
• storage_full depends on the plan. On the free plan, storage counts everything uploaded and deleting calls does not give it back: it takes another plan, or a higher limit for the account. On the others it clears when you delete old calls in the app. See Plan and limits.

The sensible thing to do is stop sending, tell whoever manages the account and keep the pending recordings to send them later. Usage and limits are in Settings → Plan & Usage, and are explained in Plan and limits.

A 500, a 502, a 503 or a connection that drops without a response points to a problem on our side or along the way. These are the ones to retry:

• Wait before you repeat the request, and wait longer on each attempt: 5 seconds, 30 seconds, 2 minutes.
• Always send the same external_id. If the first request did arrive, the second one does not duplicate the call.
• After several failed attempts, leave the recording in a queue for later instead of continuing to retry.

If a request has several problems, you see the first one in this list:

1. The key (unauthorized).
2. The format of the body (bad_request) and the presence of the file (no_file).
3. That the file is audio (not_audio) and is not empty (empty_file).
4. Whether the external_id already exists: in that case the response is 200 and nothing else is checked.
5. The agent (agent_required, unknown_agent).
6. The size (file_too_large), the storage (storage_full) and the minutes (no_minutes).