Leer el status_code del contenedor de Instagram antes de publicar

¿Qué es el status_code del contenedor de Instagram?

Publicar en Instagram a través de la API ocurre en dos llamadas, y el status_code del contenedor de Instagram es el campo que te dice si la segunda va a funcionar. La primera llamada crea un contenedor con POST /<IG_ID>/media. La segunda lo publica con POST /<IG_ID>/media_publish. Entre las dos hay una transcodificación asíncrona que no ves, y la propia referencia de Meta lo dice sin rodeos: "Video uploads are asynchronous, so receiving a container ID does not guarantee that the upload was successful."

El campo vive en el nodo IG Container. Meta lo define como "The container's publishing status" y lo lees con una sola petición:

curl -X GET \
  'https://graph.instagram.com/17889615691921648?fields=status_code&access_token=IGQVJ...'

{
  "status_code": "FINISHED",
  "id": "17889615691921648"
}

¿Qué significa cada valor de status_code?

Meta documenta cinco valores y ninguno más. Las definiciones de abajo son las que aparecen impresas en la referencia de IG Container y repetidas palabra por palabra en la guía de publicación de contenido.

Dos de esos cinco son terminales en el sentido de que ninguna espera los cambia. ERROR y EXPIRED significan los dos que el contenedor que tienes en la mano está muerto. FINISHED es el único valor que significa adelante.

Hay un segundo campo que merece la pena pedir en la misma llamada. copyright_check_status devuelve matches_found como booleano y su propio status con los valores completed, error, in_progress o not_started. Un reel puede llegar a FINISHED en status_code mientras la comprobación de derechos sigue en in_progress, que es una de las razones por las que una publicación que parecía lista puede volver descontenta.

¿Con qué frecuencia dice Meta que hay que consultar el contenedor?

Meta da una sola frase de orientación: "We recommend querying a container's status once per minute, for no more than 5 minutes." Eso son cinco peticiones, en total, por contenedor.

La cifra merece que te quedes mirándola, porque la misma documentación fija la vida del contenedor en 24 horas. Cinco minutos de sondeo cubren aproximadamente el 0,35 por ciento de la ventana en la que el contenedor es válido. Meta nunca dice qué debería hacer un cliente con un contenedor que sigue en IN_PROGRESS en el minuto seis. La documentación simplemente se acaba.

En la práctica, un reel largo que sigue transcodificándose en el minuto cinco sigue transcodificándose, y el contenedor aún sirve durante 23 horas y 55 minutos más. El techo de cinco minutos se lee como un consejo sobre cuánto machacar el endpoint y no como una afirmación sobre cuándo un contenedor se vuelve irrecuperable. Tomarlo por lo segundo tira contenedores que habrían terminado.

¿Cuánto dura un contenedor de Instagram antes de caducar?

Los contenedores caducan a las 24 horas. La referencia de IG User Media lo indica en su lista de limitaciones generales, y la definición de EXPIRED lo repite desde el otro lado: el contenedor "was not published within 24 hours."

La misma lista añade una segunda cifra que importa cuando encolas publicaciones en bloque: "An Instagram account can only create 400 containers within a rolling 24 hour period." Eso es un presupuesto de contenedores, no de publicaciones, y cuenta cada contenedor que creas lo publiques o no. Un bucle de reintentos que reconstruye un contenedor en cada fallo se lo come rápido.

El presupuesto de publicación es una cifra aparte, y aquí la propia guía de Meta se contradice dentro de la misma página. La sección Rate Limit de la guía de publicación de contenido dice "Instagram accounts are limited to 100 API-published posts within a 24-hour moving period." La sección Limitations del carrusel, más abajo en esa misma página, dice "Accounts are limited to 50 published posts within a 24-hour period." Las dos frases están vigentes. Las dos añaden que un carrusel cuenta como una publicación. Quien construya contra esto debería consultar GET /<IG_ID>/content_publishing_limit y fiarse de eso antes que de cualquiera de los dos párrafos, que es el enfoque que seguimos en el análisis del límite de publicación de contenido de Instagram y del tope de 100 posts por 24 horas.

¿Qué haces cuando status_code devuelve ERROR?

Pide el campo status en ese mismo contenedor. La definición que Meta da de ese campo es la parte útil: "Publishing status. If status_code is ERROR, this value will be an error subcode."

Así que status_code te dice que algo se rompió y status te dice qué. Los subcódigos que más aparecen en un contenedor fallido vienen de la tabla de códigos de error de Instagram de Meta:

El último es el honesto. El arreglo que Meta recomienda para 2207053 es "Generate a new container and use it to try again," y señala que el subcódigo "should only affect video uploads."

Cuatro de esos siete se pueden arreglar antes incluso de crear un contenedor, validando el archivo contra las especificaciones publicadas. Las reglas del pie de foto están en la nota sobre el límite de 2.200 caracteres del pie de foto, y las de vídeo en el desglose de lo que acepta la API de Reels de Instagram.

¿Qué haces cuando status_code devuelve EXPIRED?

Empezar de cero. No hay ningún endpoint que reviva un contenedor caducado, ni parámetro de prórroga, ni operación de actualización sobre el nodo. La referencia de IG Container dice "This operation is not supported" tanto en Creating como en Updating y Deleting. Un contenedor es de solo lectura desde tu lado.

La tabla de errores de Meta confirma el remedio en la columna de solución recomendada del subcódigo 2207020, cuyo mensaje dice The media you are trying to access has expired. Please try to upload again. El arreglo que da es "Generate a new container ID and use it to try again."

Hay un subcódigo cercano que se confunde con la caducidad y no es lo mismo. El subcódigo 2207008 devuelve The media builder with creation id = {creation-id} does not exist or has been expired. Meta lo llama un "Temporary error publishing a container" y aconseja "Try again 1-2 times in the next 30 seconds to 2 minutes. If unsuccessful, generate a new container ID." Así que el mensaje dice caducado y la guía dice reintenta. Reintenta antes de reconstruir.

¿Por qué falla media_publish cuando status_code dice FINISHED?

Porque FINISHED describe el contenedor, no la cuenta. Tres fallos sobreviven a un FINISHED limpio.

El subcódigo 2207027 devuelve The media is not ready for publishing, please wait for a moment, y el arreglo de Meta es comprobar el estado del contenedor y publicar cuando ponga FINISHED, lo cual es circular cuando FINISHED es exactamente lo que acabas de leer. Trátalo como una condición de carrera y reintenta.

El subcódigo 2207042 devuelve You reached maximum number of posts that is allowed to be published by Content Publishing API. El contenedor está bien; lo que se agotó es el cupo diario. El consejo de Meta es "Advise the app's user to try again the following day."

El subcódigo 2207050 devuelve The Instagram account is restricted. Meta explica que la cuenta "is inactive, checkpointed, or restricted" y que el único camino adelante pasa por la app de Instagram, no por la API. Es el mismo muro que hay detrás de la mayoría de razones que la gente encuentra cuando pregunta por qué no puede publicar en Instagram.

Preguntas frecuentes

¿Cuántos valores puede devolver status_code?

Cinco. IN_PROGRESS, FINISHED, PUBLISHED, ERROR y EXPIRED. La referencia de IG Container de Meta lista exactamente estos y ninguno más.

¿Un contenedor de foto necesita sondeo?

La sección de resolución de problemas de Meta plantea el sondeo de estado en torno al vídeo, porque los contenedores de imagen se resuelven en la llamada de creación. Pedir status_code en un contenedor de imagen sigue funcionando y sigue devolviendo uno de los cinco valores.

¿Cuánto hay que esperar entre consultas?

Una vez por minuto. La redacción exacta de Meta es "We recommend querying a container's status once per minute, for no more than 5 minutes."

¿Qué pasa con un contenedor que nunca publicas?

Caduca 24 horas después de crearse y cuenta contra el límite de 400 contenedores por cada 24 horas móviles. Los contenedores sin publicar no cuentan contra el límite de publicación.

¿Puedes borrar un contenedor para liberar cuota?

No. El nodo IG Container indica Deleting como "This operation is not supported." Los contenedores se limpian solos cuando caducan.

¿Qué campo te dice por qué falló la publicación?

El campo status, no status_code. Meta documenta que cuando status_code es ERROR, el valor de status es un subcódigo de error que luego buscas en la tabla de códigos de error de Instagram.

¿Cuántos de los subcódigos de ERROR se pueden evitar antes de crear un contenedor?

Cuatro de los siete subcódigos de la tabla de Meta se pueden evitar antes de que exista el contenedor. Revisar el archivo, sus dimensiones y la longitud del pie de foto contra las especificaciones publicadas por Meta detecta un formato de vídeo incorrecto, una relación de aspecto fuera de rango, una imagen demasiado grande o un pie de foto demasiado largo antes de subir nada, porque esas condiciones ya se conocen antes de crear el contenedor.

¿Puede un contenedor llegar a FINISHED antes de que termine la revisión de copyright?

Sí. Un reel puede alcanzar FINISHED en status_code mientras copyright_check_status todavía está en in_progress, así que el contenedor parece listo antes de que la revisión de copyright haya terminado de verdad. Ese campo devuelve matches_found como booleano y un estado completed, error, in_progress o not_started, y conviene pedirlo junto con status_code antes de publicar.

¿Por qué la propia documentación de Meta se contradice sobre el límite de publicaciones?

La sección Rate Limit de la guía de Content Publishing limita las cuentas a 100 publicaciones vía API dentro de un periodo móvil de 24 horas, mientras que la sección Limitations sobre carruseles, más abajo en la misma página, habla de un límite de 50 publicaciones en 24 horas. Ambas frases siguen publicadas. Consultar GET /<IG_ID>/content_publishing_limit y confiar en esa respuesta antes que en cualquiera de los dos párrafos evita las conjeturas.

¿El subcódigo 2207008 significa que el contenedor caducó?

No, aunque su mensaje diga "has been expired". Meta clasifica 2207008 como un error temporal y recomienda reintentar una o dos veces en los siguientes 30 segundos a 2 minutos antes de crear un contenedor nuevo. Un estado EXPIRED real, en cambio, no admite ningún reintento.