API
Errores
Códigos estables, formato uniforme y mapeo a HTTP.
Formato uniforme
Cualquier respuesta no-2xx devuelve este shape:
{
"error": {
"code": "INVALID_AUDIO_FORMAT",
"message": "Audio format must be one of: wav, mp3, ogg",
"request_id": "8e7c2a14-9f1b-4d2e-bc11-8a0e5d4f7c9e"
}
}| Campo | Tipo | Descripción |
|---|---|---|
error.code | string | Código estable, screaming snake case. Útil para switch en el cliente. |
error.message | string | Mensaje en inglés, listo para log. El frontend NO lo muestra al usuario tal cual; mapea por code a un mensaje en español. |
error.request_id | string | UUID v4 para correlacionar con CloudWatch. |
Tabla de códigos
| HTTP | code | Cuándo |
|---|---|---|
| 400 | MISSING_FIELD | Falta audio_base64 o format en el body. |
| 400 | INVALID_AUDIO_FORMAT | format no es wav, mp3 ni ogg. |
| 400 | INVALID_BASE64 | audio_base64 no decodifica. |
| 400 | AUDIO_TOO_LONG | El clip excede 30 segundos. |
| 413 | PAYLOAD_TOO_LARGE | El body decodificado excede ~6 MB (límite de Lambda síncrono). |
| 502 | EMBEDDING_FAILED | Bedrock devolvió error o timeout. |
| 502 | INDEX_QUERY_FAILED | S3 Vectors devolvió error o timeout. |
| 500 | INTERNAL_ERROR | Cualquier otro fallo. Detalle solo en CloudWatch. |
Manejo recomendado en cliente
try {
const data = await classify(blob);
renderPrediction(data);
} catch (err) {
switch (err.code) {
case 'AUDIO_TOO_LONG':
toast('Tu audio dura más de 30 segundos. Recórtalo y vuelve a intentar.');
break;
case 'PAYLOAD_TOO_LARGE':
toast('El archivo pesa más de 5 MB. Comprímelo o usa un clip más corto.');
break;
case 'EMBEDDING_FAILED':
case 'INDEX_QUERY_FAILED':
toast('Servicio temporalmente no disponible. Inténtalo en unos segundos.');
break;
default:
toast('Algo salió mal. Si persiste, comparte el request_id.');
}
}