Códigos de error

Todo error de la API y del MCP de koigrid tiene la misma forma: un código `error` estable, un `detail` legible, `issues` (campo y motivo) cuando falla una validación, un `requestId` (también en la cabecera X-Request-Id; cítalo a soporte), `retryable` (si repetir la misma petición puede salir bien) y un `docUrl` que apunta aquí. Esta lista se genera del catálogo del código.

Forma de la respuesta

HTTP/1.1 400 Bad Request
X-Request-Id: 3f2a…

{
  "error": "bad_request",
  "detail": "image: image repository name must be lowercase",
  "issues": [{ "path": "image", "message": "image repository name must be lowercase", "code": "custom" }],
  "requestId": "3f2a…",
  "retryable": false,
  "docUrl": "https://koigrid.com/docs/error-codes#bad_request"
}
CódigoSignificadoQué hacerReintentar
already_appliedYa hay una solicitud de esta cuenta.Mira la que ya existe en vez de volver a solicitar.—
already_existsEl destino ya existe.Elige otro destino o repite con overwrite: true.—
already_memberEsa persona ya es miembro.Nada que hacer.—
already_reviewedYa está revisada.Nada que hacer.—
analyze_in_progressYa hay un ANALYZE de esta base en marcha.Su resultado sale como `db.analyze.done` en la actividad.✓
app_deletedLa app se borró mientras se desplegaba.Recupérala de la papelera o créala de nuevo.—
app_not_foundLa app del despliegue ya no existe.Vuelve a crear la app y despliégala.—
app_pausedLa app está pausada.Reanúdala (o recarga saldo si se pausó por eso).—
app_sleepingLa app está dormida (sin visitas un tiempo) y esta petición no la despierta: venía de un escáner de seguridad.Visítala desde un navegador o cualquier cliente normal: esa visita la despierta.—
app_wakingLa app estaba dormida y está arrancando.Repite tras los segundos de la cabecera `Retry-After`.✓
backups_expiredLas copias de esta base han caducado.Ya no se puede restaurar; `expiredAt` dice cuándo.—
bad_headersLas cabeceras no son válidas.Pásalas como objeto de nombre a valor.—
bad_requestLa petición no es válida para este recurso.Lee `detail` (y `issues` si viene), corrige la petición y vuelve a enviarla.—
billing_disabledLos pagos no están configurados en este despliegue de koigrid.Escribe a soporte.—
billing_unavailableEl cobro no está configurado en esta instalación de koigrid.Escribe a soporte.—
bucket_too_smallEl tramo es demasiado pequeño para ese rango.Usa un tramo mayor o un rango más corto.—
budget_exceededSe ha alcanzado el tope de gasto (de la organización o del token).Sube el tope en Spend Management o espera al mes siguiente.—
build_export_failedEl build terminó pero la exportación de la imagen se cortó (E/S de la máquina, no tu código).Lanza el despliegue de nuevo.✓
build_push_failedLa imagen se construyó pero no se pudo guardar en el registro.Lee los registros del despliegue; si apuntan a koigrid, lánzalo de nuevo.—
busyYa hay otra prueba en marcha.Espera a que termine y repite.✓
canary_invalidoRuta de operador: no es una petición de canary válida.Sólo para operadores.—
cannot_change_ownerEl papel de dueño no se cambia así.Transfiere la propiedad.—
cap_reachedSe alcanzó el tope de esa recompensa.Nada que hacer hasta que se renueve.—
capacity_unavailableAhora mismo no hay sitio en la flota para este recurso.Repite más tarde o elige un tamaño menor; no se ha creado nada.✓
card_requiredEsto necesita una tarjeta guardada (también el primer recurso de una organización nueva). Guardarla no cobra nada; la primera abre 7 días de prueba gratis (hasta 2 GB de RAM).Añade una tarjeta (POST /billing/checkout-session, MCP add_payment_method), que una persona abra el enlace, y repite.—
command_not_foundEsa orden en segundo plano no existe en esta VM (o la VM se borró).Lístalas con GET /api/v1/sandboxes/vms/:id/commands.—
conflictLa petición choca con el estado actual del recurso.Vuelve a leer el recurso y repite con su estado actual.—
cost_escalationUna credencial no puede tener más tope de coste que el token que la crea.Pide un tope igual o menor que el tuyo.—
create_failedEl recurso se creó pero no llegó a arrancar.Lee `detail`, corrígelo y créalo de nuevo.—
deploy_exceptionEl despliegue paró por un error inesperado nuestro.Lánzalo de nuevo; si sigue, escribe a soporte.✓
deploy_in_progressHay otro despliegue de esta app en marcha.Espera a que termine y repite.✓
deploy_turno_agotadoEl despliegue esperó demasiado su turno.Lanza el despliegue de nuevo.✓
destino_desconocidoOperación de operador: máquina de destino desconocida.Sólo para operadores.—
directory_not_emptyEl directorio no está vacío.Repite con recursive=true para borrarlo con todo lo que contiene.—
disco_sin_medirOperación de operador: no se pudo medir el disco.Sólo para operadores: repite.✓
dns_sin_medirOperación de operador: no se pudo medir el DNS.Sólo para operadores: repite.✓
dominio_no_reservadoRuta de operador: la cuenta está fuera del dominio reservado de canary.Sólo para operadores.—
dr_copy_failedOperación de operador: falló la copia de desastre.Sólo para operadores: lee el evento y repite.✓
duplicateYa se envió.Nada que hacer.—
edge_sync_failedLa versión nueva no se pudo publicar en el edge.Lanza el despliegue de nuevo; sigue sirviendo la anterior.✓
email_mismatchLa invitación es para otro correo.Entra con el correo invitado.—
emptyEl fichero está vacío.Sube un fichero con contenido.—
environment_unreadableEl entorno guardado de esta VM no se pudo descifrar.Vuelve a ponerlo con PUT /api/v1/sandboxes/vms/:id/environment.—
es_liderOperación de operador: ese miembro es el líder.Sólo para operadores: cambia antes de líder.—
es_masterOperación de operador: esa copia es hoy el master.Sólo para operadores.—
existsYa existe algo con esa clave o ese nombre.Usa otra clave u otro nombre, o edita lo que ya existe.—
expiredHa caducado.Pide una nueva.—
fair_use_limitSupera el techo de uso justo de una cuenta (más bajo en una cuenta nueva hasta su primer pago).Escribe a soporte si necesitas más; una cuenta nueva también puede recargar saldo (POST /billing/wallet/topup).—
file_operation_failedLa operación con el fichero falló dentro de la VM.Lee `detail` (el mensaje de dentro de la VM) y repite.✓
file_too_largeEl fichero supera lo que admite esta operación (4 MB por escritura).Divídelo, o muévelo con exec (curl) o SSH.—
forbiddenLas credenciales son válidas pero no pueden hacer esto.Usa un token con el scope o el rol que pide la acción (mira `detail`).—
forbidden_hostEse host de imágenes no está en la lista permitida del proyecto.Añade el host a la configuración de imágenes y repite.—
forma_no_activaOperación de operador: esta forma de copia de desastre no está disponible para esta base (standby apagado, o la base ya es una copia promocionada).Sólo para operadores: créala como miembro.—
free_tier_limitSe alcanzó el límite del plan gratis para este recurso.Borra algo que ya no uses o añade una tarjeta.—
free_tier_waitlistedEl plan gratuito está lleno; tu organización está en la lista de espera (`position`).Espera a que te admitan (recibirás un aviso) o añade un medio de pago para saltártela.✓
fuente_obligatoriaUn precio comprobado necesita la URL https de donde se leyó.Envía al menos una entrada en `fuentes` que empiece por https://.—
funcion_desconocidaEsa función no está en el catálogo de la comparativa.Usa una clave de las que lista `ops-competidor funcion registrar` (definiciones en lib/comparison.ts).—
giftcard_unavailableYa no hay tarjetas regalo; las recompensas son crédito de koigrid.Canjéalo como crédito.—
health_unknownNo se pudo saber si el contenedor nuevo estaba sano.Lanza el despliegue de nuevo; si se repite, lee los registros de ejecución.✓
host_errorEl host de la VM no pudo completar la operación (por nuestra parte); la VM quedó como estaba.Repite; si se repite, escribe a soporte con el requestId.✓
idempotency_in_progressUna petición con esta Idempotency-Key aún se está procesando.Repite con la misma clave en unos segundos para recibir su resultado.✓
image_pull_failedNo se pudo descargar la imagen (no existe, es privada sin credenciales o el nombre está mal).Revisa el nombre y la etiqueta de la imagen y, si es privada, las credenciales.—
image_pull_timeoutDescargar la imagen tardó más de lo permitido.Lanza el despliegue de nuevo; una imagen más pequeña despliega antes.✓
importe_invalidoEl importe no es válido.Usa un importe dentro de los límites de `detail`.—
insufficient_balanceEl saldo no alcanza.Baja el importe.—
insufficient_scopeA la conexión le falta un permiso que necesita esta acción.Vuelve a conectar concediendo el permiso que dice `detail`.—
internalUn error inesperado por nuestra parte.Repite; si sigue, escribe a soporte citando `requestId`.✓
internal_registry_cred_failedkoigrid no pudo emitir la credencial interna del registro (fallo nuestro, no de tu app).Lanza el despliegue de nuevo.✓
invalidEl valor o la invitación no es válida.Lee `detail`.—
invalid_amountFalta el importe o no es válido.Envía `amountCents` como entero positivo, o null para apagarlo.—
invalid_argumentsLa herramienta se llamó con argumentos que no encajan.Lee `detail`: dice qué argumento falta o está mal.—
invalid_bodyEl cuerpo tiene que ser un objeto JSON.Envía un objeto JSON (`{…}`), no una lista ni un valor suelto.—
invalid_bucketEl tamaño de tramo de la serie no es válido.Usa uno de los tamaños que lista `detail`.—
invalid_detailsFaltan los datos de la reclamación o no son válidos.Lee `detail` y complétalos.—
invalid_graceEl margen es mayor de lo permitido.`detail` da el límite; usa un margen menor.—
invalid_grantEl secreto del grant no es válido o se revocó.Usa un grant válido o crea uno nuevo.—
invalid_hoursEl rango en horas no es válido.Usa un número entero de horas dentro del rango permitido.—
invalid_jsonEl cuerpo no es JSON válido.Envía un cuerpo JSON con `content-type: application/json`.—
invalid_manifestEl manifiesto del proyecto no es válido.Lee `detail` y corrige el manifiesto.—
invalid_modeEse modo de cobro no existe.Usa uno de los modos que lista `detail`.—
invalid_nameEl nombre no sigue el formato permitido.Usa minúsculas, dígitos y guiones.—
invalid_refLa referencia de imagen o de git no es válida.Usa un nombre de imagen en minúsculas (p. ej. `nginx:1.27`) o una rama/commit que exista.—
invalid_requestLa petición combina opciones que este endpoint no acepta juntas.Lee `detail`: dice qué opción quitar o qué endpoint usar.—
invalid_scheduleLa expresión cron no es válida.Usa una expresión cron estándar de 5 campos, p. ej. `*/5 * * * *`.—
invalid_scopesUno o más permisos no existen.Usa los permisos que lista /llms.txt.—
invalid_signatureLa firma de la petición no coincide.Firma el cuerpo exacto con el secreto compartido.—
invalid_sizeEse tamaño de VM no existe.Usa uno de los tamaños de la referencia de la API (small, medium, large…).—
invalid_source_urlLa URL de descarga del código subido no es válida (configuración de koigrid, no de tu app).Lanza el despliegue de nuevo; nos llega el aviso.✓
invalid_stateLa VM no está en un estado que permita esta operación (o hay otra en curso sobre ella).Lee su `status` (GET de la VM) y repite cuando lo permita.—
invalid_tagLa etiqueta de la imagen no es válida.Usa un nombre de etiqueta (no un digest `sha256:`) para esta operación.—
invalid_tokenEl token de la URL no es válido.Vuelve a copiar la URL del hook desde el panel o la API.—
invalid_urlLa URL no es válida o apunta a una dirección privada.Usa una URL https pública.—
invalid_windowLa ventana de tiempo no es válida.Revisa el inicio y el fin y su orden.—
key_requiredHace falta una clave.Pasa la clave del objeto que pide la operación.—
last_ownerLa organización se quedaría sin dueño.Haz dueño a otra persona antes.—
launch_timeoutLos contenedores tardaron más de lo permitido en arrancar.Lánzalo de nuevo; si se repite, revisa la orden de arranque y la memoria.✓
limitSe alcanzó el máximo para esta app.Borra uno que ya no uses.—
limit_reachedSe alcanzó el máximo de este recurso.Borra uno que ya no uses.—
migrate_failedNo se pudo mover la app a otra máquina.Lee `detail`; la app sigue donde estaba.—
missing_sourceLa app no tiene imagen, repositorio ni código subido que desplegar.Pon `image` o `repo` en la app, o despliega con `--dir`.—
modo_invalidoEse modo de cobro no existe.Usa uno de los modos que lista `detail`.—
motivo_cortoOperación de operador: el motivo es demasiado corto.Sólo para operadores: escribe el porqué.—
nada_que_sustituirOperación de operador: no hay copia de desastre de forma miembro que sustituir por una standby (no hay, ya es standby, o hay una sustitución a medias).Sólo para operadores: pide una copia normal, o retira antes la vieja de una sustitución a medias.—
name_takenOtro recurso de este proyecto ya tiene ese nombre.Elige otro nombre o borra antes el anterior.—
no_canary_en_cajaRuta de operador: ese producto no tiene canary en caja.Sólo para operadores.—
no_capacityNingún host de VMs tiene sitio ahora para esta VM.Repite en unos minutos o usa un tamaño menor.✓
no_dataFalta el dato obligatorio.Pasa el parámetro que nombra `detail`.—
no_dr_copyOperación de operador: no hay copia de desastre.Sólo para operadores.—
no_es_canaryRuta de operador: esa cuenta no es de canary.Sólo para operadores.—
no_estableOperación de operador: el clúster no está estable.Sólo para operadores: espera a que lo esté.✓
no_existeOperación de operador: el recurso no existe.Sólo para operadores.—
no_fileNo se ha enviado ningún fichero.Envía el fichero en el campo `file` de un cuerpo multipart.—
no_leaderLa base no tiene primario en este momento (cambio de líder en curso).Repite en un minuto.✓
no_live_deployEsto necesita una app con un despliegue sirviendo.Despliega una app que sirva y repite.—
no_runnerNo hay máquina configurada para este despliegue (por nuestra parte).Lánzalo más tarde; nos llega el aviso.✓
no_runner_availableNinguna máquina tiene sitio ahora para esta app.Repite más tarde o baja su memoria; la app sigue sirviendo la versión anterior.✓
no_seatsNo quedan plazas en el programa.Espera a que quede una libre.—
no_source_archiveEl código subido ya no está disponible.Vuelve a subir el código (`deploy --dir`).—
no_urlNo hay URL que probar.Despliega antes la app o pasa una URL.—
no_walletNo hay cartera a la que enviar el pago.Añade tu cartera (red y dirección) y repite.—
not_a_directoryLa ruta existe pero no es un directorio.Usa la ruta de un directorio, o léela como fichero.—
not_a_fileLa ruta existe pero no es un fichero.Lístala como directorio, o usa la ruta de un fichero.—
not_admittedLa solicitud a la beta no está aprobada.Espera a la revisión o mira su estado.—
not_configuredEsta función aún no está configurada para tu organización.Configúrala antes (mira `detail`).—
not_foundEl recurso no existe o no es de tu organización.Revisa el id; lista los recursos para encontrar el bueno.—
not_gitLos previews necesitan una app desplegada desde Git.Usa una app con repositorio.—
not_memberEsa persona no es miembro de la organización.Revisa el id del miembro.—
not_pendingEsa acción de mantenimiento no está pendiente en esta base: no hay nada que aplicar ya.Lee pendingMaintenance en GET /api/v1/databases/:id y aplica una de las acciones que aparezcan.—
not_readyEl recurso aún se está creando.Espera a que su estado sea `running` y repite.✓
not_yetAún es pronto para este paso.`detail` dice desde cuándo se abre.—
nothing_to_roll_backNo hay un despliegue anterior al que volver.Despliega una versión que funcione.—
oferta_desconocidaEsa oferta de competidor no está en el registro.Usa un id de `ops-competidor ofertas` (lib/competidores/registro.ts), o añade la oferta allí primero.—
operacion_en_cursoOperación de operador: hay otra operación en marcha sobre ese recurso.Sólo para operadores: espera a que termine.✓
org_no_encontradaNo se encontró la organización.Revisa el token: tiene que ser de una organización que exista.—
otro_grupoOperación de operador: el destino es de otro grupo.Sólo para operadores.—
pago_no_configuradoEl cobro no está configurado en esta instalación de koigrid.Escribe a soporte.—
payment_method_requiredEsto necesita un medio de pago guardado.Añade una tarjeta con POST /api/v1/billing/checkout-session (cuerpo vacío) y repite.—
plan_concedidoLa organización tiene un plan concedido por koigrid; no hay nada que pagar.Nada que hacer; para cambiarlo, escribe a soporte.—
plan_grantedLa organización tiene un plan concedido por koigrid; no hay nada que pagar.Nada que hacer; para cambiarlo, escribe a soporte.—
plan_limitTu plan no incluye más de este recurso.Borra uno que no uses o añade un medio de pago.—
planes_retiradosLos planes están retirados: koigrid cobra lo reservado, por horas.Añade una tarjeta en vez de elegir plan.—
plans_retiredLos planes se sustituyeron por precio por recurso.Añade un medio de pago (POST /billing/checkout-session con el cuerpo vacío).—
port_conflictDos despliegues eligieron el mismo puerto a la vez.Lanza el despliegue de nuevo.✓
precio_invalidoEl precio del competidor no tiene la forma esperada (ProviderPricing).Lee `detail`: nombra cada campo mal. Los campos desconocidos se rechazan a propósito.—
project_not_foundEse proyecto no existe en esta organización.Revisa el id del proyecto.—
project_scopeEl token está limitado a otro proyecto.Usa un token de este proyecto o uno de toda la organización.—
protected_pathEsa ruta está protegida (/, /root y los directorios del sistema).Borra lo que hay dentro en su lugar.—
query_errorLa sentencia SQL falló en la base.Lee `detail` (el error de la base) y corrige la sentencia.—
rate_limitedDemasiadas peticiones.Baja el ritmo y repite tras la cabecera `Retry-After`.✓
recursos_vivosRuta de operador: la cuenta aún tiene recursos vivos.Sólo para operadores: bórralos antes.—
registry_auth_failedkoigrid no pudo entrar en el registro de imágenes con las credenciales de la app.Revisa las credenciales del registro (usuario/token) guardadas en la app.—
replica_not_readyUna réplica arrancó pero nunca llegó a estar lista para recibir tráfico.Lee los registros de ejecución: revisa el puerto y la ruta de salud.—
replica_unhealthyUna réplica no pasó su comprobación de salud tras arrancar.Lee los registros de ejecución de esa réplica.—
resize_rejectedEste cambio de tamaño no es posible para la caché.Lee `detail`: suele ser un tamaño menor que lo que guarda.—
restore_gapEse instante cae en una ventana sin copia utilizable.Elige un instante anterior o posterior al hueco que dice `detail`.—
restore_out_of_rangeEse instante está fuera del rango restaurable de la base.Elige un instante dentro de `restorableRange`, o restaura sin targetTime.—
rotation_unavailableLa rotación de la contraseña no puede hacerse ahora.Lee `detail` y repite más tarde.✓
runner_unreachableNo se pudo llegar a la máquina que ejecuta la app (por nuestra parte).Lanza el despliegue de nuevo; la app sigue sirviendo la versión anterior.✓
scale_out_transition_in_progressEsta app aún está apagando el reparto (llevando el tráfico a su runner y esperando a que caduquen las cachés de DNS).Espera a `app.scale_out_configured` o `app.scale_out_off_incompleto` en la actividad (unos minutos) y repite.✓
scale_out_transition_interruptedEl apagado del reparto de esta app se interrumpió (el proceso se reinició a mitad); koigrid lo reanuda solo.Nada que hacer: verás `app.scale_out_off_reanudado` y después `app.scale_out_configured` en la actividad. Si no termina, repite PUT /apps/:id/scale-out {"enabled":false}.—
scope_escalationUn token no puede crear otro con más permisos que los suyos.Pide sólo scopes que ya tenga el token actual.—
scope_no_retiradoOperación de operador: el scope de Patroni sigue en etcd.Sólo para operadores.—
scopes_invalidosRuta de operador: permisos no válidos para un token de canary.Sólo para operadores.—
server_errorFalta un ajuste del servidor (por nuestra parte).Repite más tarde; si se repite, escribe a soporte con el requestId.✓
sin_endpointOperación de operador: la base no tiene endpoint de escritura que la copia standby pueda seguir.Sólo para operadores.—
sin_organizacionRuta de operador: la cuenta no tiene organización.Sólo para operadores.—
sin_sitioOperación de operador: no hay sitio en el destino.Sólo para operadores.—
sin_tarjetaEsto necesita una tarjeta guardada.Añade una tarjeta (POST /billing/checkout-session) y repite.—
too_bigLa prueba pide más de lo permitido.Baja el ritmo o la duración (límites en `detail`).—
too_largeEl contenido supera el tamaño permitido.Envía un fichero más pequeño o pártelo.—
too_longUn valor es más largo de lo permitido.Acórtalo al límite que dice `detail`.—
too_many_pointsEse rango y ese tramo dan demasiados puntos.Usa un tramo mayor o un rango más corto.—
tool_failedLa herramienta no pudo completar la acción.Lee `detail`; si parece culpa nuestra, escribe a soporte con el requestId.—
transfer_failedLa VM no pudo bajar o subir el fichero por la URL firmada.Repite; si sigue fallando, comprueba que la VM tiene red (exec: curl -I https://storage.koigrid.com).✓
unauthorizedFaltan credenciales o no son válidas.Envía `Authorization: Bearer <token>` con un token válido y sin caducar.—
unavailableEl servicio no está disponible temporalmente.Repite más tarde.✓
unhealthyEl contenedor arrancó pero no pasó su comprobación de salud.Lee los registros de ejecución: revisa el puerto en que escucha y la ruta de salud.—
unknown_lineEsa línea de recompensa no existe o está apagada.Usa una de GET /rewards/lines.—
unknown_memberEse miembro no es de esta base.Usa uno de los nombres de members[] de la respuesta (los nombres de Patroni de GET /databases/:id).—
unresolved_referenceUn valor del entorno referencia un secreto o recurso que no existe en este proyecto (o no está listo).Corrige el ${{…}} que nombra `detail`: crea la variable compartida con PUT /api/v1/config, o usa el nombre exacto de la base, caché o app.—
unsafe_for_third_partiesEl entorno tiene safeForThirdParties encendido, así que no puede llevar nada tuyo (ninguna referencia ${{…}}).Quita las referencias que nombra `detail` y pasa valores literales, o apaga safeForThirdParties.—
upload_missingAún no se ha subido nada a esa uploadUrl.Sube antes el fichero con PUT a uploadUrl y después llama a upload-complete.—
upstream_errorEl servidor de origen respondió con un error.Revisa la URL de origen; repite más tarde.✓
usage_not_verifiedkoigrid no tiene constancia del uso que pide esta reclamación.Usa antes el producto (un despliegue sirviendo) y reclama.—
validation_failedUno o más campos no pasan la validación.Cada entrada de `issues` dice el campo (`path`) y por qué; corrige esos campos.—
valor_invalidoEl valor de una función tiene que ser yes, partial, no o na.Envía uno de: yes | partial | no | na.—
vm_not_readyLa VM está pausada, parada o fallida, así que no puede hacer esto; no va a cambiar sola.Reanúdala (pausada) o arráncala (parada) antes; el `detail` dice cuál.—
vm_scopeEste token está acotado a una VM y sólo vale en las rutas de esa VM.Usa /api/v1/sandboxes/vms/<su VM>/…, o un token de la organización para lo demás.—
vm_setting_upLa VM todavía está corriendo un script de arranque bloqueante de su entorno; la petición esperó 60 s.Síguelo con GET /api/v1/sandboxes/vms/:id/commands/<commandId>/stream (el `detail` trae el commandId), o repite en unos segundos.✓
vm_startingLa VM todavía está arrancando o reanudándose; la petición esperó 60 s y aún no estaba lista.Repite la misma petición en unos segundos.✓
vms_unavailableAhora mismo no se pueden crear VMs para agentes (no hay servidor de VMs disponible, o las altas están cerradas por mantenimiento). Las VMs que ya existen siguen igual.Prueba más tarde, o usa Sandboxes (POST /api/v1/sandboxes) mientras tanto; escribe a soporte si se alarga.—