---
title: "Códigos de error de la API de Instagram: cuáles reintentar"
date: 2026-09-14
author: "InvisibleAPI Team"
canonical_id: handling-instagram-api-errors
locale_slug: codigos-error-api-instagram
category: engineering
tags:
- publishing-api
summary: "Meta documenta qué significa cada error de publicación de Instagram, no qué hacer con él. Aquí están los códigos documentados en cuatro decisiones: reintentar, corregir, avisar o parar."
draft: false
template: blog
image: blog/handling-instagram-api-errors/handling-instagram-api-errors-hero-01-es.png
faq:
- question: "¿Qué significa el código de error 9007 de la API de Instagram?"
answer: "El subcódigo 2207027 dentro del código 9007 significa que el contenido todavía no está listo para publicarse. La indicación de Meta es consultar el estado del contenedor y publicar cuando marque FINISHED. No vuelvas a crear el contenedor y no lo trates como un fallo: consúltalo. Meta sugiere comprobarlo cada minuto aproximadamente durante un máximo de cinco minutos."
- question: "¿Se puede reintentar el error 190 de la API de Instagram?"
answer: "No. El código 190 significa que el token de acceso caducó. Repetir la misma llamada con el mismo token produce el mismo error. La cuenta tiene que volver a conectarse para que se emita un token nuevo, así que es una acción del usuario y no un fallo temporal."
- question: "¿Cuántas publicaciones permite al día la API de publicación de contenido de Instagram?"
answer: "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. La cifra antigua de 25 publicaciones sigue circulando mucho y no es lo que dice la documentación hoy. Superar el límite devuelve el código 9 con el subcódigo 2207042."
- question: "¿Meta indica qué errores de la API de Instagram son temporales?"
answer: "No en la tabla de referencia. La referencia de códigos de error de Meta da un mensaje y una acción recomendada en prosa, sin columna de error temporal. La respuesta de error sí incluye un campo booleano is_transient, así que la señal existe en el momento del fallo aunque la documentación no publique un mapa por código."
- question: "¿Cómo reintento una publicación fallida de Instagram sin publicar dos veces?"
answer: "Añade una clave de idempotencia a la petición original. Con InvisibleAPI defines clientRequestId al crear el trabajo de publicación, y una llamada repetida con el mismo valor no publica dos veces. Sin clave de idempotencia, cualquier reintento tras un tiempo de espera agotado arriesga una publicación duplicada, porque no puedes distinguir una petición que falló de una que funcionó en silencio."
seo:
title: "Códigos de error de la API de Instagram"
description: "Códigos de error de la API de Instagram y qué hacer con cada uno. Lo que Meta documenta, lo que omite y cómo clasificar un fallo antes de reintentarlo."
og_image: blog/handling-instagram-api-errors/handling-instagram-api-errors-hero-01-es.png
structured_data: article
---
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](/es/api-de-publicacion/) 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.
{{product-cta:publish-to-instagram}}
## 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.
| Categoría | Qué pasó | Qué hace tu código |
|---|---|---|
| `invalid_publish_data` | La petición incumplió una regla de la plataforma. Texto demasiado largo, proporción fuera de rango, demasiados elementos en el carrusel. | No reintentar. Corrige el contenido y crea un trabajo nuevo. |
| `retryable_provider_failure` | El proveedor falló de una forma que suele resolverse sola. Contenido todavía en proceso, un contenedor caducado, un error de servidor. | Reintentar tras esperar. Este caso se reintenta de forma automática. |
| `provider_action_required` | Una persona con acceso a la cuenta tiene que hacer algo. Volver a conectar un permiso caducado, resolver una restricción. | Deja de reintentar y avisa al titular de la cuenta. |
| `platform_software_failure` | El fallo es nuestro, no de la plataforma ni tuyo. | Nada. Se dirige al soporte técnico. |
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](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/error-codes). Los códigos 190 y 368 están en la [guía de gestión de errores de la Graph API](https://developers.facebook.com/docs/graph-api/guides/error-handling). Los códigos 4, 17 y 32 se definen en la [página de límites de frecuencia](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/). 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.
**Revisa la URL que estás citando.** `developers.facebook.com/docs/instagram-platform/reference/error-codes` devuelve un 404. Se ha repetido en suficientes artículos de terceros como para parecer canónica. La página que sí existe es `developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/error-codes`, que también es a donde redirige ahora la ruta antigua `/docs/instagram-api/reference/error-codes`. Verificado el 14 de septiembre de 2026.
## 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.
| Código | Subcódigo | Qué documenta Meta |
|---|---|---|
| 100 | 2207028 | Un carrusel necesita al menos 2 elementos y como máximo 10 |
| 100 | 2207040 | Más etiquetas por contenido de las permitidas, con un máximo de 20 menciones |
| 36000 | 2207004 | La imagen es demasiado grande para descargarla, y debe pesar menos de 8 MiB |
| 36003 | 2207009 | La proporción está fuera del rango permitido de 4:5 a 1.91:1 |
| 36004 | 2207010 | El texto supera el máximo de 2.200 caracteres |
| 352 | 2207026 | El formato de vídeo no es compatible, así que usa MOV o MP4 |
| 9004 | 2207052 | No se pudo obtener el contenido desde la URI que indicaste |
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`.
| Código | Subcódigo | Qué documenta Meta |
|---|---|---|
| 9007 | 2207027 | El contenido no está listo para publicarse, así que consulta el estado del contenedor |
| 24 | 2207008 | El constructor de contenido no existe o caducó. **Meta lo llama error temporal e indica reintentar una o dos veces entre 30 segundos y 2 minutos.** |
| -2 | 2207003 | La descarga del contenido tarda demasiado |
| -2 | 2207020 | El contenido caducó, así que genera un contenedor nuevo |
| -1 | 2207001 | Un error de servidor de Instagram |
| -1 | 2207032 | La creación del contenido falló, así que vuelve a crearlo |
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.
| Código | Subcódigo | Qué documenta Meta |
|---|---|---|
| 25 | 2207050 | La cuenta de Instagram está restringida, y el usuario tiene que resolverlo en la aplicación |
| 4 | 2207051 | La actividad está restringida porque se sospecha que la publicación es spam |
| 190 | . | El token de acceso caducó, así que hace falta uno nuevo |
| 368 | . | Bloqueo temporal por incumplimiento de las políticas |
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](/es/docs/cuentas-sociales/reconectar-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](/es/pricing/) explica contra qué se cuenta la factura, y la [guía de precios de la API de Instagram](/es/blog/precios-api-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:
```bash
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:
```json
{
"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:
```ts
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" };
}
}
```
**Sobre los nombres de campo.** La forma de la petición está confirmada en la referencia de la API: `targets`, `mediaItems` con su `mediaType` y `sourceUrl`, `caption`, `requestedPublishAt` y `clientRequestId`, y la llamada de creación devolviendo 202. Lo que sigue sin confirmar es la respuesta del trabajo: el nombre del array `deliveries` y el campo `failureCategory`. Compruébalos en [la referencia de la API](https://app.invisibleapi.ai/docs/static/openapi.en.html) antes de publicar código que los lea.
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/plantillas/failed-social-media-post-recovery/) 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.
{{product-cta:start-free-trial}}
## Fuentes
Las cuatro páginas se consultaron el 14 de septiembre de 2026.
- [Referencia de códigos de error de la plataforma de Instagram](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/error-codes), para todos los códigos y subcódigos de publicación de arriba
- [Guía de publicación de contenido de Instagram](https://developers.facebook.com/docs/instagram-platform/content-publishing), 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](https://developers.facebook.com/docs/graph-api/guides/error-handling), para los códigos 1, 2, 4, 17, 190, 368 y 506
- [Límites de frecuencia de la Graph API](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/), para los códigos 4, 17, 32, 613 y 80002 y las cabeceras de uso