Errores

Cuando una petición no se puede atender, la API responde con un código HTTP de error y un cuerpo JSON con esta forma:

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

Programa contra code, no contra message. Los códigos son estables. Los mensajes están en inglés, están pensados para que los lea una persona y su redacción puede cambiar.

La petición está mal y seguirá estándolo si la repites igual. No la reintentes: corrige lo que envías.

• bad_request tiene dos causas. La primera, enviar el archivo como cuerpo de la petición en lugar de dentro de un formulario. La segunda, que la petición pese 20 MB o más: es el tope de la API, y por encima de él el formulario no llega a leerse. Si el error solo aparece con las grabaciones largas, es esta.
• no_file significa que el formulario ha llegado bien pero sin archivo. El campo tiene que llamarse exactamente file.
• empty_file es un archivo de cero bytes. Si te ocurre, comprueba que tu sistema no envía la grabación antes de haber terminado de escribirla en disco.
• not_audio significa que el archivo no declara un tipo audio/… y que su nombre no termina en una extensión de audio. Revisa cómo nombra tu sistema el archivo dentro del formulario.
• file_too_large significa que el archivo cabe en una petición pero supera el máximo por archivo de tu plan. Igual que el caso anterior, se resuelve comprimiendo el audio: para voz, MP3 a 64 kbps en mono es suficiente.

Comprueba que la cabecera es Authorization: Bearer ck_…, con un espacio tras Bearer y sin comillas ni saltos de línea alrededor de la clave. Si es correcta, puede que alguien la haya revocado: mira la lista en Integraciones. No reintentes con la misma clave.

La petición es correcta, pero la cuenta no puede aceptar más por ahora. Reintentar enseguida no sirve.

• no_minutes y calls_limit se resuelven solos cuando empieza el siguiente periodo, o ampliando los límites de la cuenta.
• storage_full se resuelve eliminando llamadas antiguas en la app.

Lo razonable es parar el envío, avisar a quien lleve la cuenta y guardar las grabaciones pendientes para enviarlas después. El uso y los límites están en Ajustes → Plan y uso, y se explican en Plan y límites.

Un 500, un 502, un 503 o una conexión que se corta sin respuesta indican un problema en nuestro lado o en el camino. Estos sí se reintentan:

• Espera antes de repetir y alarga la espera en cada intento: 5 segundos, 30 segundos, 2 minutos.
• Envía siempre el mismo external_id. Si la primera petición sí llegó, la segunda no duplica la llamada.
• Tras varios intentos fallidos, deja la grabación en una cola para más tarde en lugar de insistir.

Si una petición tiene varios problemas, verás el primero de esta lista:

1. La clave (unauthorized).
2. El formato del cuerpo (bad_request) y la presencia del archivo (no_file).
3. Que el archivo sea audio (not_audio) y no esté vacío (empty_file).
4. Si el external_id ya existe: en ese caso la respuesta es 200 y no se comprueba nada más.
5. El tamaño (file_too_large), el almacenamiento (storage_full), los minutos (no_minutes) y las llamadas del periodo (calls_limit).