Manejo de errores

Maneja errores correctamente con códigos de error estándar.

Formato de respuesta de error

Todos los errores de API siguen un formato JSON consistente.

{
  "error": {
    "code": "error_code_here",
    "message": "A human-readable description of the error."
  }
}

Códigos de error

Estado	Código	Descripción
`401`	`missing_api_key`	No se proporcionó encabezado X-API-Key.
`401`	`invalid_api_key`	La clave API proporcionada es inválida, expirada o revocada.
`402`	`quota_exceeded`	Se ha excedido la cuota mensual de solicitudes.
`422`	`invalid_image`	Campo image faltante, base64 inválido o excede 5MB.
`422`	`invalid_request`	El cuerpo de la solicitud no es JSON válido.
`502`	`inference_error`	El servicio ML no está disponible temporalmente. Reintente con backoff.

Ejemplos de respuestas de error

Clave API faltante (401)

{
  "error": {
    "code": "missing_api_key",
    "message": "No API key provided. Include your key in the X-API-Key header."
  }
}

Imagen inválida (422)

{
  "error": {
    "code": "invalid_image",
    "message": "Image exceeds the maximum size of 5 MB."
  }
}

Error de inferencia (502)

{
  "error": {
    "code": "inference_error",
    "message": "ML inference service is temporarily unavailable. Please retry."
  }
}

Mejores prácticas

Siempre verifique el código de estado HTTP antes de analizar el cuerpo de la respuesta.
Implemente backoff exponencial para errores 502.
Monitoree el uso de cuota mediante los encabezados de respuesta.
No reintente errores 401 o 422.
Use el campo error.code para manejo programático de errores.

Ejemplo de reintento

Ejemplo JavaScript con backoff exponencial:

async function analyzePalm(imageBase64, apiKey, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const res = await fetch(
      "https://api.trace-line.site/v1/palm/analyze",
      {
        method: "POST",
        headers: {
          "X-API-Key": apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ image: imageBase64 }),
      }
    );

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

    const error = await res.json();

    // Only retry on transient errors
    if (res.status !== 502) throw error;

    // Exponential backoff: 1s, 2s, 4s
    await new Promise((r) =>
      setTimeout(r, 1000 * Math.pow(2, attempt))
    );
  }

  throw new Error("Max retries exceeded");
}