Errores
Todos los fallos tienen la misma forma, así que un solo manejador cubre todos los endpoints.
Forma del error
Todos los fallos tienen la misma forma. type es la clase sobre la que ramificar, code es el identificador estable del problema concreto y param nombra el campo culpable cuando lo hay. Trata message como texto para una persona leyendo un log: puede cambiar.
4xx / 5xx
{
"error": {
"type": "invalid_request_error",
"code": "scheduled_for_too_far",
"message": "On Free, posts can be scheduled up to 30 days ahead; every paid plan schedules any time. The latest time accepted now is 2026-10-22T10:00:00.000Z.",
"param": "scheduledFor"
}
}| Tipo | Significa |
|---|---|
| authentication_error | La clave falta, está mal formada, no existe o está revocada. Siempre 401; code indica cuál. |
| permission_error | La clave es válida pero le falta el permiso, o la cuenta detrás no tiene suscripción activa. 403. |
| invalid_request_error | Algo de la petición está mal. 400, o 404 para una publicación que no existe en tu cuenta. |
| rate_limit_error | Se alcanzó un tope. 429, con Retry-After. |
| api_error | Algo se rompió de nuestro lado. 500. Se puede reintentar con la misma clave de idempotencia. |
Ramifica sobre code, nunca sobre message. Los códigos son parte del contrato; las frases no.
Códigos de error
| Código | Estado y significado |
|---|---|
| api_key_missing | 401 — falta la cabecera Authorization: Bearer. |
| api_key_malformed | 401 — el valor no tiene forma de clave de Antwork. |
| api_key_unknown | 401 — no existe ninguna clave con este id y secreto. |
| api_key_revoked | 401 — la clave se revocó en ajustes. |
| access_token_invalid | 401 — el token de acceso OAuth de una app asociada (Canva) no es válido o caducó; la app lo renueva. |
| insufficient_scope | 403 — la clave no tiene el permiso que necesita esta llamada. |
| subscription_inactive | 403 — la cuenta de la clave no tiene una suscripción activa. |
| account_under_review | 403 — la cuenta está en revisión y todavía no puede crear un espacio. |
| workspace_limit | 402 — se ha alcanzado el límite de espacios de trabajo del plan (Free tiene uno); los planes de pago tienen espacios ilimitados. |
| storage_limit_reached | 402 — el archivo llevaría el almacenamiento de medios del propietario del espacio de trabajo, sumando todos sus espacios, por encima del límite de su plan. No se ha guardado nada, y lo ya guardado no cambia. Borra medios que ya no necesites o mejora el plan. |
| role_forbidden | 403 — en Agency, la persona de la clave es editora en este espacio de trabajo, y solo el titular y los admins pueden cambiar sus ajustes. |
| approval_required | El workspace exige aprobación para lo que se publica, así que solo su propietario puede cambiar una publicación ya publicada. |
| invalid_body | 400 — el cuerpo no es un objeto JSON. |
| invalid_posting_settings | Se rechazó la configuración de publicación de la cuenta: un valor está fuera de rango (maxPostsPerDay por encima del máximo de la plataforma en el plan, un intervalo de más de 1440 minutos, una franja que no es {day 1-7, "HH:MM"}, una zona horaria desconocida). El mensaje indica cuál. |
| no_posting_slots | scheduledFor: "next_slot" en una cuenta sin franjas de publicación. Define posting.slots con PATCH /api/v1/accounts/{id} o envía una hora concreta. No se programó nada. |
| no_free_slot | scheduledFor: "next_slot", pero todas las franjas están ocupadas o llenas según los límites de la cuenta en los próximos 30 días. Añade franjas o envía una hora concreta. No se programó nada. |
| accounts_required | 400 — falta accounts o está vacío. |
| too_many_accounts | 400 — más cuentas de las que admite una petición. |
| invalid_text | 400 — text no es una cadena. |
| invalid_texts | 400 — texts no es un objeto de cadenas indexado por id de cuenta. |
| invalid_media | 400 — media no es un array de cadenas. |
| media_not_hosted | 400 — una URL de media no está en tu biblioteca de Antwork. |
| media_not_in_library | 400 — una URL de posts[].media no es un archivo de la biblioteca de medios de este espacio de trabajo. |
| invalid_hashtags | 400 — los hashtags de una publicación no son un array de textos. |
| invalid_user_tags | 400 — los userTags de una publicación no son un array de objetos. |
| invalid_scheduled_for | 400 — scheduledFor no es una hora ISO 8601 válida. |
| scheduled_for_in_past | 400 — scheduledFor está en el pasado. |
| scheduled_for_too_far | 400 — scheduledFor supera el horizonte de programación. |
| workspace_required | 400 — tienes varios espacios de trabajo y no enviaste workspaceId. |
| workspace_not_found | 400 — workspaceId no es un espacio de trabajo tuyo (404 cuando es un filtro de lista). |
| no_targets_accepted | 400 — no se aceptó ninguna cuenta y ninguna dio un motivo más concreto. |
| invalid_status | 400 — status no es uno que acepte este endpoint: un filtro de lista acepta los estados de publicación, una edición de publicación solo draft, un webhook active o disabled. |
| invalid_limit | 400 — limit no es un número entero dentro del rango. |
| invalid_cursor | 400 — cursor no lo emitió esta API. |
| invalid_filter | 400 — un filtro de la lista está mal formado, o es una combinación de filtros que ningún índice resuelve. |
| invalid_name | 400 — el name del espacio falta, está vacío o pasa de 60 caracteres. |
| invalid_website | 400 — website no es una URL https. |
| invalid_logo_url | 400 — logoUrl no es una URL https. |
| invalid_timezone | 400 — timezone no es un nombre de zona horaria IANA como Europe/Madrid. |
| invalid_preferred_times | 400 — preferredTimes no es una lista de horas HH:MM. |
| invalid_tag_outbound_links | 400 — tagOutboundLinks no es true ni false. |
| post_not_found | 404 — no existe esa publicación en tu cuenta. |
| post_already_published | 409 — la publicación ya está publicada y el cambio era más que text solo, o la plataforma no permite editar; envía solo text en una plataforma que lo permita. |
| post_not_editable | 409 — solo se puede editar un borrador, una publicación programada, una fallida o una pending_approval. |
| edit_not_supported_on_platform | La publicación está en una plataforma que no deja a las apps cambiar una publicación ya publicada (X, Instagram, Threads, TikTok, Bluesky). Bórrala y publica la versión nueva, o publica una nueva. |
| live_post_not_found | La publicación consta como publicada, pero Antwork no tiene su id en la plataforma, así que no hay nada que editar allí. |
| youtube_manage_unavailable | 409 — la publicación es un vídeo de YouTube y cambiarlo desde Antwork (título, descripción, subtítulos, lista de reproducción) necesita un permiso de YouTube que Google aún está verificando para Antwork. Por ahora cámbialo en YouTube Studio; el mensaje trae el enlace. |
| reconnect_required | 409 — el canal de YouTube se conectó antes de que Antwork pidiera el permiso que necesita este cambio. Vuelve a conectarlo en Conexiones, acéptalo y envía el cambio de nuevo. No se ha cambiado nada. |
| account_unavailable | La cuenta en la que salió la publicación ya no está conectada a este workspace. Vuelve a conectarla para editar la publicación. |
| not_published | 409 — la publicación aún no está publicada, así que no tiene comentarios que leer ni responder. |
| comments_requires_upgrade | 402 — leer y responder comentarios forma parte de todos los planes de pago, y el propietario del espacio de trabajo está en Free. |
| comments_unsupported | 409 — esta red, o este tipo de cuenta, no comparte comentarios con apps (TikTok, Pinterest, Discord, Telegram, Google Business Profile, Slack, perfiles personales de LinkedIn), o sus comentarios aún no están en Antwork (Instagram, Facebook, Threads, YouTube). |
| reconnect_for_comments | 409 — la red rechazó el permiso de la cuenta para leer o responder comentarios. Vuelve a conectar la cuenta en Antwork. |
| campaign_not_found | 404 — no existe esa campaña en tu cuenta. |
| too_many_posts | 400 — la campaña tiene más publicaciones de las que envía una llamada; envíalas una a una. |
| account_not_found | 404 — no existe esa cuenta social en tu cuenta. |
| account_inactive | 409 — la cuenta está desconectada, así que no se pueden leer sus publicaciones. Vuelve a conectarla en Antwork. |
| media_not_found | 404 — no existe ese archivo en una biblioteca de medios tuya. 400 cuando media en una publicación nombra un id de biblioteca que este espacio de trabajo no tiene. |
| media_in_use | 409 — el archivo sigue adjunto a una publicación; usedInPosts las enumera. |
| webhook_not_found | 404 — no hay ningún webhook así en un espacio cuyos ajustes puedas cambiar. |
| invalid_webhook_url | 400 — url no es una URL https en el puerto por defecto que apunte a una dirección pública. |
| invalid_events | 400 — events no es una lista no vacía de post.scheduled, post.published, post.failed, account.needs_reconnect, account.disconnected, routine.due. |
| invalid_description | 400 — description no es un texto de 200 caracteres como máximo. |
| webhook_limit | 409 — el espacio ya tiene 5 webhooks. Borra uno antes. |
| webhooks_requires_upgrade | 402 — los webhooks están en todos los planes de pago y el dueño del espacio está en Free. El mensaje incluye el enlace para mejorar el plan. |
| recurring_requires_upgrade | 402 — los posts recurrentes y evergreen forman parte de todos los planes de pago, y el propietario del workspace está en Free. El mensaje lleva el enlace para mejorar el plan. |
| recurrence_not_found | 404 — el post no se repite ni está en la cola evergreen, o la recurrencia no está en un workspace al que perteneces. |
| invalid_recurrence | 400 — repeat, evergreenPerWeek o variants tiene un formato incorrecto, o el cuerpo pide a la vez repetir y evergreen. El mensaje dice qué corregir. |
| recurrence_unsupported_platform | 409 — los posts de esta red no pueden repetirse. TikTok pide al usuario que confirme los ajustes de cada post. |
| post_not_bound | 409 — el post no está vinculado a una cuenta conectada, así que Antwork no puede crear más. |
| repeat_needs_scheduled_post | 409 — solo un post programado o publicado puede repetirse: su hora es donde empiezan las repeticiones. Prográmalo primero. |
| discovery_requires_upgrade | 402: leer publicaciones de otras personas (platform-posts:fetch con source) está en todos los planes de pago, y el dueño del espacio está en Free. El mensaje incluye el enlace para mejorar el plan. |
| discovery_x_weekly_limit | 429: el dueño del espacio ya usó las búsquedas de X sin caché de esta semana. Las que ya hizo se guardan un día y siguen respondiendo; las nuevas se abren el lunes (UTC), indicado en X-Discovery-Resets-At. |
| creator_not_found | 404: la red no tiene ninguna cuenta con ese handle (en Instagram, ninguna cuenta pública de empresa o de creador). |
| instagram_reconnect_for_discovery | 409: leer creadores de Instagram necesita una cuenta de Instagram conectada con el inicio de sesión de Facebook, y esta usa el de Instagram. Vuelve a conectarla con "Reconectar con el inicio de sesión de Facebook" en el menú de la cuenta en Conexiones; sus posts y su calendario se mantienen. |
| remote_http_error | 400 — el servidor del enlace respondió con un error HTTP en vez del archivo. |
| not_a_file | 400 — el enlace es una página web, no un archivo. |
| unsupported_type | 400 — el archivo no es una imagen, un vídeo o un PDF admitido. |
| too_large | 400 — el archivo supera el límite de tamaño de su tipo. |
| empty_file | 400 — el enlace devolvió un archivo vacío o cortado. |
| blocked_url | 400 — la URL no es una dirección pública de internet en el puerto por defecto. |
| fetch_timeout | 400 — el servidor tardó demasiado en enviar el archivo. |
| fetch_failed | 400 — no se pudo conectar con el servidor (error de DNS, TLS o conexión). |
| private_link | 400 — un enlace de Google Drive, Docs, Presentaciones, Dropbox u OneDrive cuyo archivo la nube no entrega: no está compartido como 'Cualquier persona con el enlace', se ha eliminado o el enlace está mal. |
| folder_link | 400 — un enlace a una carpeta de Google Drive, Dropbox u OneDrive; envía el enlace de un archivo de dentro. |
| design_link | 400 — una página de diseño, para compartir o de reproducción de Canva o InVideo; exporta el archivo desde la herramienta y súbelo. |
| url_ingest_rate_limited | 429 — esta clave descargó demasiados enlaces en 10 minutos. Espera lo que indique Retry-After. |
| platform_read_rate_limited | 429 — esta clave hizo demasiadas lecturas que van a una plataforma (platform-posts:fetch, include=recentPosts) en 10 minutos. Espera lo que indique Retry-After. |
| storage_failed | 500 — el archivo se descargó pero no se pudo guardar. Reinténtalo. |
| platform_error | 502 — la red rechazó o no respondió a la petición de comentarios, la limitó, o la cuota de API de Antwork con ella (X) está agotada por ahora. El message dice cuál. Reinténtalo más tarde. |
| idempotency_in_flight | 409 — una petición con esta Idempotency-Key sigue en curso. |
| idempotency_key_reused | 422 — esta Idempotency-Key se usó con otro cuerpo. |
| rate_limit_burst | 429 — por encima del límite por minuto. |
| rate_limit_daily | 429 — por encima del límite diario. |
| internal_error | 500 — algo falló por nuestra parte. |
Cuando no se acepta ninguna cuenta de una petición de creación, la respuesta es un 400 cuyo code es el motivo de rechazo de la primera cuenta (ver la tabla siguiente), con el array posts completo al lado.
Por qué se rechazó una cuenta
El reason de una entrada rejected o failed en la respuesta de creación.
| Código | Estado y significado |
|---|---|
| account_unresolved | El id no es una cuenta conectada en este espacio de trabajo. |
| platform_not_available | Obsoleto y ya no se devuelve: todas las plataformas que admite Antwork están en la API. Se mantiene para que las integraciones que lo comprueban sigan funcionando. |
| invalid_option | Un ajuste de options es desconocido, tiene un valor que la plataforma no admite o es de una plataforma que no está en la petición. En la forma accounts rechaza toda la petición (400, con param); en posts rechaza esa publicación. |
| tiktok_settings_need_the_creator | Se enviaron ajustes de TikTok donde se compartirían o quedarían en la edición de un borrador (options.tiktok en la forma accounts, o PATCH /posts/{id}). TikTok exige que el usuario los elija en cada publicación: envíalos en el posts[].options de esa publicación, o como tiktokSettings en /publish o /schedule. |
| unknown_pinterest_board | boardId no es un tablero de esta cuenta de Pinterest. |
| unknown_slack_channel | El channel de Slack no es uno del que sea miembro la persona que conectó la cuenta. GET /api/v1/accounts/{id} lista los canales como slackChannels. |
| pinterest_board_create_failed | Pinterest no creó el tablero de newBoardName (un nombre ya usado, o la cuenta necesita reconectarse). |
| invalid_instagram_tag | El username de una etiqueta de Instagram no es un nombre de usuario de Instagram. |
| linkedin_company_wrong_platform | Se envió una etiqueta de empresa para una cuenta que no es de LinkedIn. |
| linkedin_company_not_in_text | La página de LinkedIn etiquetada no se menciona en el texto. Añade @ y el nombre de la página donde debe ir el enlace. |
| linkedin_company_invalid | La etiqueta de empresa no es una URL de página de LinkedIn ni su nombre personalizado. |
| linkedin_company_not_found | LinkedIn no tiene ninguna página en esa dirección. |
| linkedin_company_lookup_failed | No se ha podido consultar la página en LinkedIn ahora mismo, o hay que volver a conectar la cuenta. |
| text_empty | No hay texto para esta cuenta y la plataforma lo necesita. |
| text_too_long | El texto supera el límite de caracteres de la plataforma. |
| too_many_mentions | Más @menciones de las que admite la plataforma (Instagram: 20 por texto). |
| too_many_cashtags | Más cashtags ($SÍMBOLO) de los que admite la plataforma (X: uno por publicación). |
| media_required | La plataforma necesita una imagen o un vídeo y no se adjuntó ninguno. |
| unsupported_media | La plataforma no acepta uno de los tipos de archivo adjuntos, o esta combinación de ellos (Facebook lleva fotos o un vídeo, no ambos). |
| video_too_long | El vídeo es más largo de lo que permite la plataforma. |
| video_too_short | El vídeo es más corto de lo que permite la plataforma (Instagram: 3 segundos). |
| video_unsupported | La plataforma no acepta la velocidad de fotogramas o la resolución del vídeo. |
| media_too_large | Un archivo supera el tamaño que acepta la plataforma. |
| image_aspect_ratio | La proporción de la imagen está fuera de lo que acepta la plataforma. |
| invalid_thread | El hilo de X no es válido: una parte supera los 280 caracteres, tiene más de 25 publicaciones, o más de una publicación lleva un enlace. |
| tiktok_privacy_required | Una publicación de TikTok iba a publicarse o programarse sin audiencia elegida, por una vía que no admite ajustes de TikTok (la forma accounts). Envíala en la forma posts[] con sus ajustes, o como borrador y después /publish con tiktokSettings. |
| tiktok_choices_needed | Una publicación de TikTok iba a salir sin las elecciones del usuario, o con elecciones que TikTok no ofrece ahora a este creador. El error (o el post_result) lleva tiktokChoices: el apodo del creador, las opciones de privacidad sin valor por defecto, cada interacción (desactivada, y si el creador la desactivó), la declaración comercial con las etiquetas que muestra TikTok, el vídeo más largo permitido y la declaración con los enlaces de TikTok. Pregunta al usuario cada una y envía sus respuestas con userConsented: true; problems lista lo que fallaba en los ajustes enviados. |
| tiktok_creator_unavailable | TikTok dice que este creador no puede publicar ahora mismo (demasiadas publicaciones en 24 horas, el límite del día o un token que reconectar). No se publicó nada. Vuelve a intentarlo más tarde, o reconecta la cuenta si el mensaje lo dice. |
| pinterest_board_required | Un pin de Pinterest iba a publicarse sin tablero. Indica boardId en las opciones de Pinterest. |
| slack_channel_required | Una publicación de Slack iba a publicarse sin canal, en una cuenta que aún no tiene canal por defecto. Pasa channel (un id o #nombre) en las opciones de Slack. |
| instagram_tag_unavailable | Una publicación de Instagram etiqueta a una persona (usernames) que Instagram se negó a etiquetar en la última publicación de esta cuenta: la cuenta cambió de nombre o se eliminó, es privada o no permite etiquetas. Quita la etiqueta o corrige el usuario. Se mantiene 7 días. |
| token_invalid | La conexión de la cuenta ha caducado. Vuelve a conectarla en Antwork. |
| token_refresh_failed | No se pudo renovar la conexión. Vuelve a conectarla en Antwork. |
| account_pending_payment | La cuenta se conectó por encima de las cuentas gratuitas del plan y espera el pago. No puede publicar hasta terminar el pago en Antwork (connectionsUrl). |
| quota_exceeded | Has agotado las publicaciones de tu plan en este ciclo. |
| daily_cap_reached | Esta cuenta ya alcanza su máximo diario en las 24 horas alrededor de la hora pedida. Prográmala más tarde o reparte las publicaciones. |
| schedule_queue_full | Esta cuenta ya tiene el máximo de publicaciones que Antwork pone en cola por cuenta (100 en el plan Free, 1.000 en el de pago). Programa más cuando se hayan publicado algunas. |
| account_limit_reached | Se alcanza un límite que fijó el propietario de la cuenta (posting.maxPostsPerDay o posting.minGapMinutes) en torno a la hora pedida. nextFreeAt es la primera hora en la que cabe; el borrador se conserva. |
| duplicate_post | El texto repite una publicación reciente de esta cuenta de X o Threads, y ambas lo tratan como spam. |
| posting_too_close | Otra publicación sale en esta cuenta de X o Threads con menos de 10 minutos de diferencia. Sepáralas más. |
| x_link_requires_paid | Una publicación de X con un enlace, desde una cuenta del plan Free. Los enlaces en X están incluidos en los planes de pago; quita el enlace o mejora tu plan. |
| x_fair_use_reached | El propietario ha usado las publicaciones en X que incluye su plan en este ciclo de facturación y no le quedan créditos de publicaciones de X. Compra créditos en la página de facturación o espera a que se renueve el ciclo; las demás redes no se ven afectadas. |
| x_link_credits_needed | Una publicación de X con un enlace, por encima de las publicaciones con enlace que incluye el plan en este ciclo, sin créditos de enlaces de X. Compra créditos en la página de facturación o quita el enlace. |
| schedule_failed | La publicación se creó pero no se pudo poner en cola (failed). Existe y no se enviará. |
¿Algo no cuadra? Dinos cuál.