# Errores de la API de Units

Cada rechazo lleva un `code` estable, una `description` legible, `details` (`code: description`) y un `docs_url` que apunta a la sección correspondiente de abajo. Las cifras que permiten actuar a un programa van en el cuerpo: `retry_after_seconds` (también la cabecera `Retry-After`) y, para `no-warm-unit`, `warm_ready` y `warm_starting`.

```json
{
  "code": "no-warm-unit",
  "description": "No warm unit is ready, accepting and unallocated",
  "details": "no-warm-unit: No warm unit is ready, accepting and unallocated",
  "docs_url": "https://docs.zaroz.cloud/units/errors#no-warm-unit",
  "retry_after_seconds": 5,
  "warm_ready": 0,
  "warm_starting": 2
}
```

Decide por `code`, nunca por `description`. Un rechazo nunca es un éxito parcial y un límite nunca detiene una unidad que ya está en marcha.

## policy-not-code

**HTTP 409.** La política no está en modo `code`.

Qué hacer: Pon `mode: "code"` en la política. Leer y cambiar etiquetas funciona en cualquier modo.

## unit-input-differs

**HTTP 409.** Una unidad en marcha ya tiene esta clave con otros `labels` o `user_data`.

Qué hacer: Usa `PATCH` para etiquetas; para `user_data` detén la unidad e inícialá con el valor nuevo, o usa allocate.

## no-warm-unit

**HTTP 409.** No hay ninguna unidad caliente lista. El cuerpo trae `warm_ready`, `warm_starting` y `retry_after_seconds`.

Qué hacer: Espera `retry_after_seconds` y reintenta, envía `if_none: "create"` o sube `warm_units`.

## region-unreachable

**HTTP 503.** La región no es alcanzable. Una asignación se deshizo.

Qué hacer: Las unidades en marcha siguen sirviendo. Reintenta con espera creciente.

## container-unit-limit

**HTTP 409.** El Workload ya ejecuta el máximo de unidades con pod.

Qué hacer: Destruye o detén una unidad, o sube `max_units` en la política.

## stopped-unit-limit

**HTTP 409.** El Workload guarda el máximo de 1.000 unidades detenidas.

Qué hacer: Destruye las unidades detenidas que ya no necesites.

## org-unit-limit

**HTTP 409.** Tu organización está en su límite de unidades entre todos los Workloads.

Qué hacer: Libera una unidad en otro sitio o pide a soporte subir el límite (50 por defecto).

## start-rate

**HTTP 429.** Demasiados arranques de unidades esta hora (600 por organización por defecto). Viene `Retry-After`.

Qué hacer: Espera `Retry-After`. Reutiliza unidades (allocate, iniciar una detenida) en lugar de crear nuevas.

## spend-cap

**HTTP 409.** Arrancar superaría el tope mensual de gasto de unidades extra.

Qué hacer: Sube `spend_cap_cents` en la política. Asignar una unidad ya caliente sigue permitido; su relleno se rechaza.

## not-provisioned

**HTTP 409.** El servicio todavía no ejecuta unidades.

Qué hacer: Termina antes la configuración del Workload.

## container-busy

**HTTP 503.** Hay otro cambio en curso en las unidades de este Workload. Viene `Retry-After`.

Qué hacer: Reintenta tras la cabecera.

## invalid-idempotency-key

**HTTP 400.** `Idempotency-Key` debe tener de 1 a 64 caracteres ASCII imprimibles.

Qué hacer: Acórtala o límpiala.

## invalid-unit-key

**HTTP 400.** La clave no tiene de 1 a 40 minúsculas, dígitos o guiones, empezando y acabando en letra o dígito.

Qué hacer: Corrige la clave.

## reserved-unit-key

**HTTP 400.** La clave está reservada: `u` más dígitos, empieza por `w-` o `zaroz`, o es una palabra de ruta como `allocate`.

Qué hacer: Elige otra clave.

## too-many-labels

**HTTP 400.** Más de 16 etiquetas.

Qué hacer: Envía como máximo 16.

## invalid-label-key

**HTTP 400.** Una clave de etiqueta no cumple `^[a-z0-9]([a-z0-9_.-]*[a-z0-9])?$` o supera los 32 caracteres.

Qué hacer: Corrige la clave.

## label-value-too-long

**HTTP 400.** Un valor de etiqueta supera los 64 caracteres.

Qué hacer: Acórtalo o ponlo en `user_data`.

## invalid-label-value

**HTTP 400.** Un valor de etiqueta tiene caracteres de control.

Qué hacer: Quítalos.

## labels-too-large

**HTTP 400.** El mapa de etiquetas supera los 2 KiB serializado.

Qué hacer: Envía menos etiquetas o más cortas.

## user-data-too-large

**HTTP 400.** `user_data` supera los 64 KiB serializado.

Qué hacer: Guarda la carga en otro sitio y pasa una referencia.

## user-data-too-deep

**HTTP 400.** `user_data` tiene más de 32 niveles de anidamiento.

Qué hacer: Aplánalo.

## cursor-expired

**HTTP 410.** (eventos) El cursor es anterior a los 30 días conservados. El cuerpo trae `resume_after`.

Qué hacer: Continúa desde `resume_after`.

## Rechazos compartidos

Estos rechazos no son propios de las unidades: cualquier ruta de la API puede devolverlos, y una ruta de Units enlaza su `docs_url` a la sección correspondiente.

## resource-not-found

**HTTP 404.** El Workload, la unidad, el webhook o el registro que pides no existe, o tu token no puede verlo.

Qué hacer: Comprueba el identificador y la organización a la que pertenece el token.

## invalid-field-value

**HTTP 400 o 422.** Un parámetro de consulta o un campo del cuerpo está mal formado o fuera de rango. `details` nombra el campo.

Qué hacer: Corrige el campo indicado en `details`. No se cambió nada.

## business-rule-violation

**HTTP 409 o 422.** La petición está bien formada, pero una regla de la plataforma la rechaza en el estado actual.

Qué hacer: Lee `details`: indica la regla y qué cambiar. Repetir la misma petición no ayudará.

## rate-limit-exceeded

**HTTP 429.** Demasiadas peticiones a esta ruta. Se envía `Retry-After`.

Qué hacer: Espera `Retry-After` y reintenta.

## service-unavailable

**HTTP 503.** Una dependencia que necesita la petición no está accesible ahora. No se cambió nada.

Qué hacer: Reintenta con espera creciente. Las unidades en marcha siguen sirviendo.

## internal-server-error

**HTTP 500.** La plataforma falló al atender la petición.

Qué hacer: Reintenta una vez. Si persiste, contacta con soporte con la hora de la petición.

## log-store-unavailable

**HTTP 503.** El almacén de registros no se puede leer ahora. Las unidades en marcha no se ven afectadas.

Qué hacer: Reintenta con espera creciente.

## unit-not-running

**HTTP 409.** La unidad no está en marcha, así que no tiene salida en vivo que leer ni retransmitir.

Qué hacer: Arranca la unidad, o lee sus registros almacenados.

## code-units-exist

**HTTP 409.** Aún existen unidades creadas por tu código, así que el Workload no puede salir del modo código.

Qué hacer: Destruye esas unidades y repite el cambio.