Gestión de errores

Pixapi devuelve códigos de estado HTTP y códigos de error legibles por máquina. Tu aplicación debería separar los errores corregibles por el usuario de los fallos transitorios de infraestructura.

Estructura del error

{
  "error": {
    "code": "model_unavailable",
    "message": "The selected model is temporarily unavailable.",
    "request_id": "req_..."
  }
}

Categorías de gestión

Categoría	Ejemplos	Acción
Errores de petición	invalid_request, model_not_found	Corrige la validación de la petición.
Auth errors	unauthorized	Solicita una clave de API válida.
Errores de facturación	insufficient_credits	Muestra Créditos o Facturación.
Policy errors	prompt_rejected	Pide al usuario que revise la entrada.
Transient errors	rate_limited, model_unavailable	Reintenta con backoff.

Patrón de reintento

Usa backoff exponencial para fallos transitorios.

const delays = [500, 1000, 2000];
for (const delay of delays) {
  const res = await callPixapi();
  if (res.ok) return res;
  if (![429, 500, 503].includes(res.status)) break;
  await new Promise((resolve) => setTimeout(resolve, delay));
}

IDs de petición

Registra request_id cuando esté disponible. Inclúyelo al abrir un ticket de soporte para que el equipo pueda rastrear una llamada fallida al modelo sin exponer el prompt original a sistemas no relacionados.