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.
Code
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.