Solución de problemas

Errores de deploy / API

400 validation

Un campo no pasó la validación. La respuesta lista los campos con problema:

{ "error":"validation", "details": { "fieldErrors": { "name": ["name must be dns-safe (a-z, 0-9, -)"] } } }

• name: solo minúsculas, números y guiones.
• domain: debe ser un hostname válido (sin espacios, backticks ni caracteres raros).
• dockerfile / context: solo rutas relativas — sin / inicial, sin ...
• Los campos opcionales en blanco están bien (vacío = omitido).
• “one of image, repo or services is required”: no mandaste ninguno.
• “exactly one service must have public: true”: las apps multi-servicio necesitan exactamente un servicio público.

403 quota_exceeded

Tu org llegó al tope max_apps. Borrá una app sin usar, o pedile al admin que suba el tope. Redesplegar una app existente siempre se permite.

400 unknown_secret

Referenciaste en envFrom / secretFiles un secret que no existe para esta app. La respuesta lista los missing. Crealo primero (ver Secrets), mirando el scope compartido vs por-app.

503 sealed

La llave maestra de la plataforma no está cargada (modo solo-memoria tras un reboot). /deploy y /secrets quedan bloqueados hasta que un operador corra POST /admin/unseal. Con la config por defecto (auto-unseal) no lo vas a ver.

401 missing_bearer_token / invalid_or_expired_token

• Falta o está mal el header Authorization: Bearer <token>.
• Los access tokens expiran (~15 min). Conseguí uno nuevo con /auth/refresh usando tu refresh token, o volvé a loguearte.

429 rate_limited

Demasiados requests a /auth desde tu IP (límite 30 / 5 min). Esperá y reintentá.

La app desplegó pero el sitio no carga

El cert / HTTPS no funciona en un dominio custom

Let’s Encrypt emite el cert en el primer request vía HTTP-01 — el DNS tiene que apuntar al servidor antes. Chequeá:

dig +short <tu-dominio>     # tiene que devolver la IP del servidor

Arreglá el DNS y reintentá. Para subdominios <name>.<ROOT_DOMAIN> esto ya lo maneja el DNS wildcard.

La app está en estado failed

Mirá el error y los logs:

curl -s $API/apps/<appId> -H "authorization: Bearer $TOKEN"   # ver last_error + deployments[].error
curl -s "$API/apps/<appId>/logs?tail=500" -H "authorization: Bearer $TOKEN"

Causas comunes:

• Build falló (apps de repo): error en el Dockerfile, ruta dockerfile/context mal, o un repo privado sin un repoToken válido.
• port incorrecto: la plataforma rutea al port donde escucha tu contenedor. Si tu app escucha en 3000 pero pusiste port: 80, da 502. Poné el port correcto y redesplegá.
• Falló el pull de la imagen: typo en el nombre/tag, o un registry privado (solo se pullean imágenes públicas).

502 / 504 desde el dominio

El contenedor no escucha en el port configurado, crasheó al arrancar, o todavía está booteando. Mirá los logs; verificá el port.

El push-to-deploy no se dispara

• El Content type del webhook tiene que ser application/json.
• El Secret en GitHub tiene que coincidir con el de la respuesta del deploy / GET /apps/:id.
• Solo los pushes a la rama configurada disparan deploy; los demás se ignoran.
• En GitHub → Webhooks → Recent Deliveries ves la respuesta (un 401 = el secret no coincide).

¿Seguís trabado?

Agarrá el id de la app y los logs/deployments recientes (comandos de arriba) y pasáselos al admin de la plataforma.