Códigos de error de la API de Instagram: cuáles reintentar

Cada fallo de publicación en Instagram acaba en una de cuatro acciones: reintentarlo, corregir la petición, pasárselo al titular de la cuenta, o parar y escalar. Acertar esa decisión es todo el trabajo. Si reintentas algo permanente, gastas cuota en una petición que nunca va a funcionar. Si das por perdido algo temporal, pierdes una publicación que habría salido al segundo intento.

Meta documenta qué significa cada código de error. No documenta cuál de las cuatro acciones tomar, y su tabla de referencia no tiene ninguna columna de error temporal. Esta guía asigna los códigos que Meta publica hoy a una decisión, usando las cuatro categorías de fallo con las que la API de publicación unificada de InvisibleAPI ya clasifica cada publicación. Todos los códigos de abajo se leyeron en la documentación de Meta el 14 de septiembre de 2026, y las páginas están enlazadas al final.

Las cuatro decisiones detrás de cada error de publicación en Instagram

InvisibleAPI clasifica cada fallo de publicación en una de cuatro categorías. No son niveles de gravedad. Cada una nombra a un responsable distinto y un paso siguiente distinto.

Lee la tabla otra vez desde el lado del lector. Las categorías uno y tres llegan las dos como un error con forma de 400 desde Instagram, y las dos son permanentes para la petición tal y como está escrita. La diferencia es quién puede arreglarlo. Esa distinción es la que una tabla de códigos en bruto no puede darte, y es la que decide si tu producto muestra un mensaje de validación o un aviso pidiendo que alguien inicie sesión.

Por qué la referencia de errores de Meta no puede decidir por ti

La documentación de Meta es precisa y detallada. Solo que está construida para responder otra pregunta. Hay tres cosas que impiden usarla como política de reintentos.

Los códigos viven en tres páginas distintas. Los subcódigos de publicación como 9007 y 2207027 están en la referencia de códigos de error de Instagram. Los códigos 190 y 368 están en la guía de gestión de errores de la Graph API. Los códigos 4, 17 y 32 se definen en la página de límites de frecuencia. Quien recibe un código 4 a secas y quien recibe un código 4 con subcódigo 2207051 tienen problemas distintos y necesitan páginas distintas.

No hay una clasificación de error temporal por código. La referencia da un mensaje y una acción recomendada en prosa. La palabra “transient” aparece en el ejemplo de respuesta, no en la tabla. Las respuestas de error de Meta sí llevan un booleano is_transient junto a error_user_title y error_user_msg, así que la señal existe en el momento del fallo. Sencillamente no es algo que puedas consultar por adelantado para construir un switch.

Las acciones recomendadas no son intervalos. “Inténtalo de nuevo” aparece en varios códigos sin ninguna indicación de cuánto esperar. En toda la tabla de publicación de Instagram hay exactamente un código con una ventana concreta: el código 24 con subcódigo 2207008, donde Meta indica reintentar una o dos veces entre 30 segundos y 2 minutos.

Códigos de error de publicación de Instagram, agrupados por qué hacer

Abajo están los códigos que Meta documenta para la publicación de contenido, ordenados por la decisión y no por el número. Donde Meta indica el comportamiento de forma explícita, se señala. En el resto, la agrupación es nuestra lectura de la acción recomendada por Meta, y conviene tratar el campo is_transient en tiempo de ejecución como la autoridad cuando los dos no coincidan.

Corrige la petición, no la reintentes

Se corresponden con invalid_publish_data. El mismo contenido va a fallar igual siempre.

La última fila merece una segunda lectura. Una URI que no sea accesible públicamente falla aquí, y por muchos reintentos que hagas un bucket privado no se vuelve público. El contenido tiene que servirse desde una URL pública, y es una restricción que conviene tener en cuenta al diseñar en lugar de descubrirla en producción.

Reintenta tras esperar

Se corresponden con retryable_provider_failure.

El 9007 es el que peor se gestiona con más frecuencia. En realidad no es un fallo: el contenedor todavía se está procesando. La propia guía de publicación de Meta indica consultar el estado del contenedor y publicar cuando marque FINISHED, comprobándolo cada minuto aproximadamente durante un máximo de cinco minutos. Los estados del contenedor son EXPIRED, ERROR, FINISHED, IN_PROGRESS y PUBLISHED. Volver a crear el contenedor ante un 9007 pone en cola una segunda subida para una publicación que iba a salir bien.

El titular de la cuenta tiene que actuar

Se corresponden con provider_action_required. Tu bucle de reintentos no puede resolver ninguno.

El código 190 es el fallo más habitual en una integración de larga vida, y es el ejemplo más claro de por qué un bucle de reintentos es la herramienta equivocada. El token ya no está. La cuenta tiene que volver a conectarse antes de que funcione nada más, que es lo que cubre la guía de reconexión y scopes. Un permiso que caduca no rompe la cuenta en sí, porque cada concesión de credenciales es independiente, así que otra concesión válida sobre la misma cuenta sigue publicando.

Escala

platform_software_failure no tiene ningún código de Meta equivalente, y ese es justo el motivo de que exista. Cubre el caso en el que la petición era válida, la plataforma estaba sana, y aun así algo se rompió por el camino. Instagram no tiene un código para eso, porque desde el lado de Instagram no pasó. Sin una cuarta categoría, los fallos de esta forma se archivan mal como temporales y se reintentan para siempre, o se archivan mal como errores de quien llama y se muestran a un usuario que no puede hacer nada al respecto. En InvisibleAPI se dirigen al soporte técnico en lugar de al titular de la cuenta.

Los errores de límite son un caso aparte

Los errores de límite se pueden reintentar, pero no ahora, y la espera es toda la respuesta. Tratarlos como un fallo temporal cualquiera es la forma de acabar bloqueado más tiempo.

El límite de publicación. La documentación de publicación de contenido de Meta indica 100 publicaciones por API dentro de una ventana móvil de 24 horas, y un carrusel cuenta como una sola publicación. Superarlo devuelve el código 9 con el subcódigo 2207042, y la indicación de Meta es reintentar al día siguiente. La cifra de 25 publicaciones al día sigue apareciendo en mucha documentación de terceros. No es lo que dice la documentación hoy, así que planifica con 100 y comprueba tú el número antes de construir un programador encima.

Los límites de frecuencia. El código 4 es el límite de la aplicación, el 17 el del usuario, el 32 el de la Pages API, el 613 un límite personalizado y el 80002 el límite por caso de uso de negocio de Instagram. La instrucción de Meta cuando te limitan es directa y conviene seguirla: deja de hacer llamadas, porque continuar aumenta el tiempo hasta que vuelvan a funcionar. Las cabeceras X-App-Usage y X-Business-Use-Case-Usage llevan tu consumo actual, y la segunda incluye estimated_time_to_regain_access en minutos. Ese campo es el único número de espera concreto que publica Meta, así que gana a cualquier intervalo que fueras a inventarte.

Tu propio techo. Al publicar con InvisibleAPI, cada cuenta conectada puede publicar 100 publicaciones por periodo de facturación, y un endpoint de límites informa del uso en vivo para que tu código lo consulte antes de empezar un lote. Comprobar el límite antes sale más barato que una cola de trabajos que fallan en el proveedor. Si lo que te ha traído aquí es la pregunta del volumen, cómo funcionan los precios por volumen explica contra qué se cuenta la factura, y la guía de precios de la API de Instagram cubre la comparación de costes más amplia.

Lógica de reintentos que lee la categoría, no el número de código

Una política de reintentos construida sobre una lista fija de enteros se pudre. Meta no publica un mapa estable de errores temporales, se añaden subcódigos, y un código que se comporta de una forma al publicar se comporta de otra en los límites de frecuencia. La lista que escribiste en enero deja de encajar con la realidad sin que nada te avise.

Basa la decisión en la clasificación. Crea el trabajo:

curl -X POST "https://api.invisibleapi.ai/api/v1/organizations/$ORGANIZATION/publishing/jobs" \
  -H "Authorization: Bearer $INVISIBLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": ["acct_ig_01"],
    "caption": "New drop, live now.",
    "mediaItems": [{ "mediaType": "image", "sourceUrl": "https://cdn.example.com/drop.jpg" }],
    "clientRequestId": "drop-0914-ig"
  }'

Un trabajo que falla vuelve con la categoría, y con una entrega por cada destino:

{
  "id": "job_01K2M4P7",
  "status": "failed",
  "clientRequestId": "drop-0914-ig",
  "deliveries": [
    {
      "target": "acct_ig_01",
      "platform": "instagram",
      "status": "failed",
      "failureCategory": "retryable_provider_failure"
    }
  ]
}

Así la decisión es un switch sobre cuatro valores en lugar de una tabla de consulta de enteros:

type Category =
  | "invalid_publish_data"
  | "retryable_provider_failure"
  | "provider_action_required"
  | "platform_software_failure";

export function decide(category: Category) {
  switch (category) {
    case "retryable_provider_failure":
      return { retry: true, backoffMs: 60_000 };
    case "invalid_publish_data":
      return { retry: false, notify: "developer" };
    case "provider_action_required":
      return { retry: false, notify: "account_owner" };
    case "platform_software_failure":
      return { retry: false, notify: "support" };
  }
}

Reintentar solo es seguro porque la llamada de creación lleva clientRequestId. Esa es la parte que casi todos los consejos sobre reintentos se dejan fuera. Cuando una petición agota el tiempo de espera no puedes distinguir una llamada que falló de una que funcionó y perdió su respuesta, así que un reintento a ciegas es una moneda al aire sobre una publicación duplicada. Una clave de idempotencia quita la moneda del aire: la llamada repetida no publica dos veces. Si quieres la versión de barrido y reintento como construcción funcionando, la plantilla de recuperación de publicaciones fallidas es la receta.

Conviene conocer los estados del trabajo antes de escribir el bucle: pending, scheduled, processing, preparing, submitted, polling, published, partial_failure, failed, action_required y canceled. Fíjate en que action_required es un estado final propio, así que un trabajo que espera al titular de la cuenta nunca se queda en una cola de reintentos fingiendo estar en curso.

Los errores que puedes frenar antes de que lleguen a Instagram

Vuelve a la primera tabla de este artículo. Casi todas las filas son una regla que se podría haber comprobado antes de que la petición saliera de tu edificio. La longitud del texto, la proporción, el número de elementos del carrusel y el formato de vídeo son todos conocidos de antemano.

Para eso está la validación previa. Cada adaptador de plataforma valida sus propias reglas antes de enviar nada, así que un incumplimiento falla con una clave de error concreta en lugar de con una ida y vuelta al proveedor. Un ejemplo real es publishing.validation.media_items.media_type_unsupported, que detecta un tipo de contenido no admitido en la puerta.

El efecto práctico es que toda una familia de códigos de Meta deja de aparecer en tus registros, y los que sí aparecen tratan de verdad sobre la plataforma y no sobre tu contenido. También cambia dónde se manifiesta el error: en la creación del trabajo, donde tu código todavía tiene el contexto, y no minutos después en una respuesta asíncrona.

Cuando un trabajo apunta a varias cuentas

Un trabajo de publicación puede apuntar a muchas cuentas conectadas a la vez, y el resultado por destino vive en las entregas del trabajo. Esto importa más de lo que parece, porque el mismo contenido puede pasar en una plataforma y fallar en otra. Un texto de 500 caracteres se publica en Instagram y falla la regla de 280 caracteres de X, en el mismo trabajo.

Un único estado de trabajo no puede con eso, y por eso partial_failure existe como estado propio. Si lees las entregas y no solo el trabajo, obtienes una respuesta por cuenta: qué destino publicó, cuál falló la validación previa y bajo qué categoría. Para una agencia que reparte una publicación de cliente entre una docena de cuentas, esa es la diferencia entre un informe útil y un punto rojo.

Deja de adivinar qué fallos debe reintentar tu código

Los códigos de error de la API de Instagram te dicen qué salió mal. Una clasificación le dice a tu código qué hacer a continuación, y eso es lo que convierte una publicación fallida en una recuperada en lugar de en un aviso que alguien tiene que leer. Conecta una cuenta de Instagram, crea un trabajo y deja que las categorías dirijan tu lógica de reintentos en vez de una lista de enteros que tienes que mantener. Cada cuenta empieza con una prueba gratuita de 7 días.

Fuentes

Las cuatro páginas se consultaron el 14 de septiembre de 2026.

• Referencia de códigos de error de la plataforma de Instagram, para todos los códigos y subcódigos de publicación de arriba
• Guía de publicación de contenido de Instagram, para el límite de 100 publicaciones en una ventana móvil de 24 horas y los estados del contenedor
• Gestión de errores de la Graph API, para los códigos 1, 2, 4, 17, 190, 368 y 506
• Límites de frecuencia de la Graph API, para los códigos 4, 17, 32, 613 y 80002 y las cabeceras de uso