Errores

Codigos HTTP

Codigo	Significado	Cuando ocurre
200 / 201	Exito	Evaluacion completada correctamente
400	Bad Request	Body invalido, campo faltante, tipo de ejercicio desconocido
401	Unauthorized	API key faltante o invalida
403	Forbidden	Licencia vencida o limite mensual alcanzado
429	Too Many Requests	Rate limit por minuto excedido
500	Internal Server Error	Error inesperado del motor

Formato de respuesta de error

Todos los errores devuelven JSON:

{
  "statusCode": 401,
  "message": "Invalid or missing API key",
  "error": "Unauthorized"
}

Para errores de validacion (400):

{
  "statusCode": 400,
  "message": [
    "area must be one of the following values: listening, reading, writing, vocabulary, grammar",
    "type must be one of the following values: multiple_choice, fill_blank, open_answer, drag_and_drop, match, word_search, crossword"
  ],
  "error": "Bad Request"
}

Errores comunes

400 - Campo content requerido

Los tipos drag_and_drop, match, word_search y crossword requieren el campo content:

{
  "statusCode": 400,
  "message": "Exercise type \"drag_and_drop\" requires the \"content\" field."
}

401 - API key invalida

{
  "statusCode": 401,
  "message": "Invalid or missing API key"
}

Verifica que el header sea x-api-key (no Authorization).

403 - Limite mensual alcanzado

{
  "statusCode": 403,
  "message": "Limite mensual alcanzado"
}

Contacta a eCondor para ampliar tu plan.

429 - Rate limit

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}

Implementa backoff exponencial en tu cliente.

Recomendaciones para el cliente

// Ejemplo de manejo de errores robusto
async function evaluarEjercicio(payload: EvaluatePayload, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const res = await fetch(ENGINE_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
      body: JSON.stringify(payload),
    });

    if (res.ok) return res.json();

    if (res.status === 429 && attempt < retries - 1) {
      await sleep(1000 * 2 ** attempt); // backoff exponencial
      continue;
    }

    throw new Error(`Engine error ${res.status}: ${await res.text()}`);
  }
}