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": "Posts can be scheduled at most 30 days ahead. The latest accepted time 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. |
| 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. |
| invalid_body | 400 — el cuerpo no es un objeto JSON. |
| 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. |
| 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. |
| invalid_option | 400 — una clave de options es desconocida, tiene un tipo incorrecto o es de una plataforma que no está en la petición. |
| no_targets_accepted | 400 — no se aceptó ninguna cuenta y ninguna dio un motivo más concreto. |
| invalid_status | 400 — el filtro status no es uno de los cuatro estados. |
| invalid_limit | 400 — limit no es un número entero dentro del rango. |
| invalid_cursor | 400 — cursor no lo emitió esta API. |
| post_not_found | 404 — no existe esa publicación en tu cuenta. |
| 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 | La cuenta es de una plataforma en la que la API aún no publica. |
| 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. |
| 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. |
| video_too_long | El vídeo es más largo de lo que permite la plataforma. |
| 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. |
| quota_exceeded | Has agotado las publicaciones de tu plan en este ciclo. |
| schedule_failed | La publicación se creó pero no se pudo poner en cola (failed). Existe y no se enviará. |