Errores

Toda respuesta fuera del rango 2xx lleva un cuerpo JSON. Ramifique según code, nunca según message: los mensajes están escritos para personas y se pueden reformular.

El sobre

{
  "detail": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Deploying needs about 1h of credit up front",
    "balance_micro": 1500000,
    "required_micro": 2305000
  }
}

Clave	Tipo	Significado
detail.code	cadena	Estable, en mayúsculas, seguro para ramificar
detail.message	cadena	Explicación de una línea para personas
Claves adicionales	varía	Contexto de ese fallo concreto

Dos fallos usan una forma distinta. Los errores de validación de la solicitud que produce el framework colocan una lista bajo detail, con una entrada por cada campo incorrecto:

{"detail": [{"type": "greater_than_equal", "loc": ["body", "disk_gb"], "msg": "Input should be greater than or equal to 10"}]}

Y un fallo inesperado del lado del servidor coloca ahí una cadena simple, como {"detail": "Internal Server Error"}. Maneje las tres formas si está escribiendo una biblioteca cliente.

Estados HTTP

Estado	Significado
200	La solicitud se completó correctamente
201	Se creó algo: una instancia, una copia de una plantilla, una clave de API
204	Se completó sin cuerpo: revocar una clave, eliminar una clave SSH
400	La solicitud está mal formada, por ejemplo un X-Org-Id que no es un id
401	El bearer token falta, no es válido, caducó, fue revocado, o es una clave de API en un endpoint de cuenta
402	El saldo de la organización no cubre la acción, o los pagos están congelados
403	Está autenticado pero no tiene permiso: acción exclusiva de administradores, organización equivocada, u objeto inmutable
404	No se encontró, o no es visible para su organización — ambos casos son deliberadamente indistinguibles
409	El estado entra en conflicto: la oferta ya está tomada, la instancia está en el estado equivocado, el nombre ya se usa
410	Ya no existe: una invitación que se usó, venció o fue revocada
413	El cuerpo de la solicitud es mayor de lo que acepta el endpoint
422	Los valores son incorrectos: un campo fuera de rango, un disco mayor que el de la máquina, un valor de enumeración desconocido
429	Demasiadas solicitudes: espere a Retry-After
503	No disponible temporalmente: un inicio que el host no pudo completar, o comprobaciones de inicio de sesión que no pueden ejecutarse ahora. Reintente en breve

Qué encuentra realmente quien alquila

Condición	Estado	Código	Qué hacer
Desplegar o iniciar cuando el saldo no cubre una hora del consumo de la organización con esa instancia en marcha (su GPU y su disco, más la GPU y el disco de las instancias en ejecución, iniciándose o en creación, y el disco de las detenidas): un saldo positivo no basta	402	INSUFFICIENT_BALANCE	Un administrador agrega créditos en la consola. El cuerpo lleva balance_micro y required_micro. Las claves de API no pueden recargar.
La oferta se alquiló entre su llamada de listado y su despliegue, o mientras se reservaba su despliegue	409	OFFER_UNAVAILABLE	Tome la siguiente oferta de su lista filtrada y reintente. No reintente con el mismo offer_id. No se creó nada.
La máquina está reservada para desconectarse antes de lo que tarda en arrancar una instancia	409	MACHINE_IN_MAINTENANCE	El cuerpo lleva next_maintenance. Despliegue en otra parte, o espere a que pase la ventana. No es un problema de capacidad —la máquina tiene GPU libres—, así que reintentar la misma oferta funciona una vez terminada la ventana.
disk_gb fuera de 10–20000	422	lista de validación	Envíe un valor dentro del rango
disk_gb mayor que el disco del host	422	DISK_TOO_LARGE	El cuerpo lleva max_disk_gb. Reintente con ese valor o uno menor, o elija una máquina más grande.
Acción exclusiva de administradores, o cualquier acción de administrador intentada con una clave de API	403	ADMIN_REQUIRED	Use un token de sesión que pertenezca a un administrador. El proceso de pago, las invitaciones y la gestión de miembros nunca están disponibles para las claves. Consulte Roles y permisos.
Revocar una clave desconocida, ya revocada o de otra organización	404	API_KEY_NOT_FOUND	Vuelva a listar GET /v1/api-keys y use un id vigente
Detener, iniciar o destruir desde un estado que no lo permite	409	INVALID_STATE	Lea primero status. El mensaje nombra el estado actual, por ejemplo Cannot start an instance while it is running.
Una plantilla vm en una máquina que no admite VM	422	OFFER_NOT_VM_CAPABLE	Filtre por ofertas cuyo vm_capable sea true
Un ssh_key_id que la credencial no puede adjuntar: no es suyo o, con una clave team, no es de un miembro actual	404	SSH_KEY_NOT_FOUND	Liste GET /v1/ssh-keys con un token de sesión y use uno de esos ids
La organización ya tiene 25 instancias sin destruir	409	INSTANCE_LIMIT_REACHED	El cuerpo lleva limit. Destruya una primero: las instancias detenidas y en error cuentan, así que detener no libera nada.
Hay una disputa de pago abierta en la organización	402	PAYMENTS_FROZEN	Los despliegues y los inicios quedan en pausa hasta que se cierre la disputa.
Una plantilla aún no publicada, que fija un CUDA más antiguo que el de la máquina o que necesita hardware que no es x86_64	422	TEMPLATE_COMING_SOON, TEMPLATE_CUDA_TOO_NEW, TEMPLATE_ARCH_UNSUPPORTED	Antes de desplegar, compare coming_soon y constraints.cuda_max y constraints.arch de la plantilla con el cuda_version de la oferta.
Una plantilla de otra organización que descarga de un registro privado, o una oferta cuya máquina el plano de control no conoce	422, 409	TEMPLATE_REQUIRES_OWNER, OFFER_NOT_PINNABLE	No se creó nada. Duplique la plantilla con sus propias credenciales de registro, o vuelva a listar las ofertas.
Iniciar una instancia cuyo host no puede aceptarlo	409, 503	HOST_UNREACHABLE, START_REFUSED, START_UNAVAILABLE	La instancia sigue stopped. Reintente más tarde; con START_UNAVAILABLE, en breve. Un START_REFUSED cuyo mensaje dice que el host ya no conserva la carga de trabajo no va a funcionar: destruya y vuelva a desplegar.
Iniciar una instancia cuyas GPU se liberaron (gpus_released) mientras otro cliente usa una de ellas	409	CAPACITY_UNAVAILABLE	La instancia sigue stopped, con su disco. Reintente más tarde; un inicio tiene que recuperar las mismas GPU, así que ninguna otra máquina u oferta sirve.
Demasiadas solicitudes de un mismo llamante	429	RATE_LIMITED	Espere los segundos del encabezado Retry-After (también en el cuerpo como retry_after_s) y luego reintente.
Un cuerpo de solicitud por encima del límite de tamaño	413	PAYLOAD_TOO_LARGE	El cuerpo lleva limit_bytes. Envíe menos: 1 MiB en la mayoría de los endpoints, 4 MiB en las plantillas.
Una instancia, oferta o plantilla que su organización no puede ver	404	INSTANCE_NOT_FOUND, OFFER_NOT_FOUND, TEMPLATE_NOT_FOUND	Compruebe el X-Org-Id que envió, y que el objeto siga existiendo

Los fallos de autenticación y de organización —TOKEN_INVALID, TOKEN_EXPIRED, NOT_A_MEMBER, ORG_MISMATCH, INVALID_ORG_ID— se tratan en Autenticación. La lista completa de códigos está en Códigos de error.

Reintentos

Respuesta	¿Reintentar?
402	No. Nada cambia hasta que lleguen créditos o, con PAYMENTS_FROZEN, hasta que se cierre la disputa.
409 INSTANCE_LIMIT_REACHED	Solo después de destruir una instancia.
409 OFFER_UNAVAILABLE	Sí, con otra oferta.
409 MACHINE_IN_MAINTENANCE	Sí, con otra máquina, o con la misma después de next_maintenance.
409 INVALID_STATE	Solo después de volver a leer la instancia y confirmar que la transición ya es válida; allowed_actions indica cuáles lo son.
409 HOST_UNREACHABLE, START_REFUSED, CAPACITY_UNAVAILABLE	Más tarde, con espera creciente. Mientras tanto la instancia sigue stopped.
429 RATE_LIMITED	Sí, después de los segundos de Retry-After.
503	Sí, tras una breve espera.
422	No. Corrija primero la solicitud. Ante INVALID_CURSOR, empiece el listado de nuevo sin cursor.
401 TOKEN_EXPIRED	Sí, una vez, con un token de sesión nuevo. Una clave shk_ no caduca, así que un 401 en una clave significa que fue revocada.

POST /v1/instances no acepta clave de idempotencia, así que un tiempo de espera agotado lo deja sin saber si el alquiler ocurrió. Resuélvalo mirando, no reintentando: GET /v1/instances y busque su label.

Reintentar con el mismo offer_id no es seguro. Una oferta es una forma, no una única ranura: una máquina a la que le quedan GPU responde otra vez a la misma oferta y usted obtiene una segunda instancia, facturada aparte, a partir de un solo despliegue pretendido. Solo devuelve 409 cuando ya no quedan unidades en esa máquina, que es exactamente el caso en el que tampoco se le habría cobrado dos veces.