Skip to main content
En lugar de un solo modelo, pasa una lista ordenada de candidatos. Si el primero falla por causa del proveedor, Geek Hub reintenta automáticamente con el siguiente, sin devolver error al cliente. La respuesta indica qué modelo finalmente respondió y el costo se calcula contra ese.

​
Sintaxis

model acepta string (1 modelo) o array (1 a 8 candidatos ordenados): 
curl -X POST https://api.geekhub.mx/v1/chat/completions \
  -H "Authorization: Bearer ghub_sk_live_TU_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": [
      "openai/gpt-5",
      "anthropic/claude-sonnet-4-6",
      "google/gemini-2.5-flash"
    ],
    "messages": [{"role":"user","content":"Hola"}]
  }'

​
Cuándo se activa el fallback

CasoClaseFallback
HTTP 429 rate limitprovider✅ Sí
HTTP 500/502/503 provider downprovider✅ Sí
HTTP 408/504 timeoutprovider✅ Sí
Network reset / connection refusedprovider✅ Sí
Contexto excedido (input > context window)provider✅ Sí
Content policy rechazó el promptprovider✅ Sí
HTTP 401/403 auth inválidauser❌ No
HTTP 400 request malformadouser❌ No
HTTP 402 saldo insuficienteuser❌ No
Modelo no existe en el catálogouser❌ No

​
Skip por pre-flight

Si un candidato no soporta una capability requerida (zdr: true, response_format) o está bloqueado por la config ZDR del org, se salta en vez de fallar. Aparece en skipped con el motivo:
  • zdr_not_verified — sin política ZDR verificada
  • zdr_org_required — org exige ZDR y el candidato no está verificado
  • structured_outputs_not_supported — sin soporte structured outputs
  • model_not_found, no_adapter — catálogo o configuración

​
Respuesta exitosa

{
  "id": "req_...",
  "model": "anthropic/claude-sonnet-4-6",
  "choices": [...],
  "usage": {...},
  "geekhub": {
    "final_model": "anthropic/claude-sonnet-4-6",
    "requested": [
      "openai/gpt-5",
      "anthropic/claude-sonnet-4-6"
    ],
    "attempts": [
      { "model": "openai/gpt-5", "error": "rate_limit" }
    ],
    "skipped": []
  }
}

​
Si fallan todos

HTTP/1.1 502 Bad Gateway

{
  "error": {
    "type": "all_candidates_failed",
    "requested": [...],
    "attempts": [...],
    "skipped": [...]
  }
}

​
Costos

El cobro se hace contra geekhub.final_model. Los intentos fallidos no generan cargo de tokens al usuario pero quedan en /dashboard/usage con statusCode ≠ 200.

​
Streaming

Con stream: true el fallback solo funciona si la falla ocurre antes del primer chunk. Una vez que tu cliente recibe tokens, no es posible cambiar de modelo; el error sale como evento SSE y se aborta.