Llevarlo a producción

Nada de esto es obligatorio para que la API funcione. Todo esto es lo que separa una integración que anda de una que sigue andando el martes a las tres de la mañana.

#Secretos

• El client_secret va en un gestor de secretos o en una variable de entorno del servidor. Nunca en el repositorio, en un frontend, en una app móvil ni en una URL.
• Una credencial por integración, no una compartida entre varias. Cuando algo se filtra, querés poder revocar eso y no todo.
• Pedí solo los scopes que usás. Es la diferencia entre un incidente acotado y uno que no lo es.
• Para cambiar de secreto sin corte, creá una credencial paralela y revocá la vieja cuando el tráfico se mudó. Rotar es el camino de emergencia: el secreto nuevo lo genera la rotación, así que hay una ventana de 401 hasta que lo desplegás.
• No loguees el Authorization ni el client_secret. Si tu framework loguea headers, filtralos explícitamente.

#Tokens

• Cacheá el access token y renovalo 60 segundos antes de expires_in. Un token que vence en vuelo produce un 401 evitable.
• Ante un 401, pedí un token nuevo y reintentá una vez. Si vuelve, no es el token: es la credencial, el usuario o la empresa.
• Con varios procesos, compartí el token en vez de que cada uno pida el suyo: la cubeta del client_id es común.
• No parsees el JWT. Sus claims son un detalle interno; si necesitás saber si sigue vigente, usá introspect.

#Turnos

• Generá la Idempotency-Key fuera del bucle de reintentos, y persistila junto al trabajo. Si tu cola reencola, la key tiene que sobrevivir al reencolado.
• Subí el timeout de lectura de tu cliente HTTP por encima de 30 minutos, o usá el stream. El valor por defecto de casi todos los clientes es demasiado corto para un turno real.
• Un chat por conversación. El límite de un turno de la API por chat no es de volumen: es lo que evita que cancelar uno cancele el otro.
• Cancelá explícitamente. Cerrar la conexión no cancela nada: el turno sigue corriendo y se te sigue cobrando hasta que termine o venza.

#Errores

• Ramificá sobre message_code, nunca sobre message.
• Reintentá 429, 500, 502, 503 y 504 con backoff exponencial y jitter. No reintentes 4xx de contrato: no mejoran por insistir.
• Respetá Retry-After cuando venga.
• Un turno que falló con 502 o 504 ya consumió su key: para volver a intentarlo, generá una nueva.
• Nunca reintentes una interacción que dio 409: aplicar dos veces la misma aprobación es peor que no saber si se aplicó.

#Observabilidad

• Guardá el X-Request-Id de cada respuesta —éxito y error— en tus logs. Es lo que hay que citar para que podamos rastrear un request de tu lado en el nuestro.
• Usá metadata para atar cada turno a un registro tuyo. Vuelve en la respuesta y en el listado de mensajes, así que no necesitás una tabla de correspondencias.
• Monitoreá X-RateLimit-Remaining y frená antes de llegar a cero.
• Alertá sobre el usage de los turnos: un cambio de prompt que duplica los tokens no rompe nada, y por eso nadie se entera.

#Consumo y licencia

Cada turno descuenta del pool de niucredits de la licencia del usuario titular de la credencial. Cuando se agota, el envío se rechaza aunque te sobre cupo de requests.

• Vigilá el consumo con Analíticas antes de que sea un incidente.
• Borrar un chat no devuelve lo consumido: el borrado es lógico y el gasto ya ocurrió.
• Si el usuario titular se va de la empresa, su credencial deja de funcionar. Para integraciones de larga vida, usá una credencial de organización o una cuenta de servicio dedicada.

#Cambios en el contrato

La versión viaja en la URL (/api/v1). Dentro de v1 los cambios son compatibles hacia adelante: pueden aparecer campos nuevos en las respuestas y valores nuevos en un enum, pero no desaparece un campo ni cambia el significado de uno existente.

• Ignorá los campos que no conocés en vez de fallar al deserializarlos.
• No asumas que un enum está cerrado: steps[].type y los code de error pueden crecer.
• En los requests pasa lo contrario: los cuerpos son estrictos, y un campo que la API no conoce devuelve 422. Mandá solo lo documentado.