Manejo de Errores - OpenModex

Formato de Respuesta de Error

Todos los errores de API devuelven un formato JSON consistente:

{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type",
    "code": "error_code"
  }
}

Tipos de Error

Estado	Tipo	Cuándo
`400`	`invalid_request_error`	Parámetros faltantes o inválidos
`401`	`authentication_error`	Clave API inválida o faltante
`403`	`permission_error`	La clave carece de permisos
`404`	`not_found_error`	Endpoint o modelo inválido
`429`	`rate_limit_error`	Demasiadas solicitudes
`500`	`server_error`	Error interno del servidor
`502`	`upstream_error`	El proveedor devolvió un error
`503`	`service_unavailable`	Interrupción temporal

Manejo de Errores en SDKs

import OpenModex, { APIError } from '@openmodex/sdk';

try {
  const response = await client.chat.completions.create({...});
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.statusCode);     // 429
    console.log(err.message);        // "Rate limit exceeded"
    console.log(err.code);           // "rate_limit_exceeded"

    if (err.isRateLimited) {
      // Wait and retry
    } else if (err.isAuthError) {
      // Check API key
    } else if (err.isServerError) {
      // Retry with backoff
    }
  }
}

from openmodex import OpenModex, APIError

try:
    response = client.chat.completions.create(...)
except APIError as e:
    print(e.status_code)   # 429
    print(e.message)       # "Rate limit exceeded"

    if e.status_code == 429:
        # Wait and retry
        pass
    elif e.status_code == 401:
        # Check API key
        pass

Reintentos Automáticos

Todos los SDKs reintentan automáticamente en errores transitorios (429, 500, 502, 503, 504) con backoff exponencial:

const client = new OpenModex({
  apiKey: 'omx_sk_...',
  maxRetries: 3,    // default: 2
  timeout: 60_000,  // default: 30000ms
});

Mejores Prácticas

Siempre capture errores — no deje que los fallos de API hagan colapsar su aplicación
Use respaldos — configure modelos de respaldo para rutas críticas
Registre el request_id — incluya response.openmodex.request_id en reportes de error para soporte
Establezca timeouts apropiados — más largos para prompts complejos, más cortos para consultas simples
Maneje errores de streaming — los streams pueden fallar a mitad de respuesta; almacene en búfer el contenido parcial