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": "Add credits before deploying an instance",
    "balance_microusd": 0,
    "required_microusd": 2290000
  }
}

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	A la organización no le queda crédito
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
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

Qué encuentra realmente quien alquila

Condición	Estado	Código	Qué hacer
Desplegar o iniciar con el saldo vacío	402	INSUFFICIENT_BALANCE	Un administrador agrega créditos en la consola. El cuerpo lleva balance_microusd y required_microusd. Las claves de API no pueden recargar.
La oferta se alquiló entre su llamada de listado y su despliegue	409	OFFER_UNAVAILABLE	Tome la siguiente oferta de su lista filtrada y reintente. No reintente con el mismo offer_id.
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 no está en su cuenta	404	SSH_KEY_NOT_FOUND	Liste GET /v1/ssh-keys con un token de sesión y use uno de esos ids
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.
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.
422	No. Corrija primero la solicitud.
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.