- Documentación
- API · Versión 1.0
- Errores
Errores
En esta página
Esta página responde, para cada rechazo de la API, a una sola pregunta: ¿hay que reintentar?
| Respuesta | Significado |
|---|---|
| No | La misma petición producirá el mismo error. Corrige la configuración, o abandona. |
| Tras corregir | Corrige el cuerpo o la cabecera y vuelve a enviar. La clave de idempotencia sigue siendo utilizable. |
| Sí | La causa es pasajera. Vuelve a enviar la misma petición, tras un plazo. |
Los dos sobres
Los rechazos de la API llevan un código estable en error.code:
{
"error": {
"code": "insufficient_scope",
"message": "This client does not hold the « destinations:read » scope.",
"required_ability": "destinations:read"
}
}
error.code es el contrato: no cambia. error.message está escrito para una persona, y puede reformularse: no lo compares nunca.
Los mensajes de la API están en inglés, sea cual sea el idioma de tu cuenta y sin tener en cuenta la cabecera Accept-Language, rechazos de negocio incluidos: reglas de los borradores y de las redes, transiciones de publicación, direcciones de webhook. Excepción: el error de un destino (targets[].error.message) que no procede de nuestras reglas de publicación — rechazo de la red al publicar, token ausente, red no configurada, fallo técnico de la entrega — puede seguir en francés, o en las palabras de la propia red. Del mismo modo, un destino que falló antes de que estos mensajes se tradujeran conserva su mensaje en francés, en la API como en los webhooks, mientras no se vuelva a lanzar. Fíate de error.code y de las claves de errors, nunca del texto. Algunos códigos llevan campos adicionales, descritos más abajo.
Los errores de validación de la petición — campo que falta, tipo erróneo, valor fuera de la lista — conservan el sobre de Laravel, sin error.code, con un estado 422:
{
"message": "Send at least one destination.",
"errors": {
"destination_ids": ["Send at least one destination."]
}
}
errors está indexado por nombre de campo. Sus mensajes están en inglés, como el resto de la API.
Rechazos de forma destacables, todos en 422 sobre el campo afectado:
- una fecha que no está en ISO 8601 (« The date must follow ISO 8601, for example 2026-10-15T09:00:00+02:00. », es decir, la fecha debe seguir la norma ISO 8601);
mediaymedia_idsenviados juntos, o más de 10 medios;- más de 30 etiquetas, o una etiqueta vacía o demasiado larga una vez formateada;
- una clave de sustitución que una red no admite (« « instagram » does not accept: « link_url » », es decir, «instagram» no acepta «link_url»), o un nombre de red desconocido;
- en
POST /webhooks, una dirección rechazada por la protección, un evento fuera del catálogo, o unbrand_idque no designa ninguna marca del espacio.
Por tanto, un cliente robusto lee error.code si existe, y errors en caso contrario.
$response = $quietSocial->post('/publications', $payload);
if ($response->failed()) {
$code = $response->json('error.code'); // null para un error de validación
$fields = $response->json('errors', []); // presente para un error de validación
}
Tabla de decisión
| Código | Estado | ¿Reintentar? |
|---|---|---|
unauthenticated |
401 | No |
insufficient_scope |
403 | No |
plan_required |
403 | Tras cambiar de plan |
workspace_suspended |
403 | Tras el levantamiento de la suspensión |
account_pending_deletion |
403 | No |
brand_unavailable |
403 | Tras la restauración de la marca |
endpoint_shared |
403 | No |
idempotency_key_required |
400 | Tras corregir |
idempotency_key_too_long |
400 | Tras corregir |
idempotency_key_in_flight |
409 | Sí |
idempotency_key_reused |
409 | No, no con esta clave |
brand_required |
422 | Tras corregir |
brand_not_found |
422 | Tras corregir |
publication_not_publishable |
422 | Tras corregir |
media_not_acceptable |
422 | No, no con este archivo |
transition_not_allowed |
409 | No |
endpoint_suspended |
409 | Tras reactivar |
not_found |
404 | No |
method_not_allowed |
405 | No |
too_many_requests |
429 | Sí, tras un plazo |
request_failed |
cualquier otro estado | 4xx: no; 5xx: sí |
| (validación, sin código) | 422 | Tras corregir |
| (fallo, sin código) | 5xx |
Sí |
Códigos de la API
unauthenticated — 401
Credenciales ausentes, ilegibles, desconocidas, erróneas, o cliente revocado. Comprueba que el identificador qsc_… se envía como nombre de usuario y el secreto qss_… como contraseña. Consulta Autenticación.
insufficient_scope — 403
El cliente está autenticado pero no tiene el permiso que exige la ruta. error.required_ability nombra el permiso que hay que hacer conceder. GET /me lista de una vez los que tienes.
plan_required — 403
El cliente es válido, pero el plan de su espacio no incluye la API (Gratis y Solo). La clave se conserva: vuelve a funcionar en cuanto el espacio pasa a Studio o superior.
workspace_suspended — 403
El espacio del cliente está suspendido por el Editor, que envió el motivo a su propietario. La clave se conserva: vuelve a funcionar cuando se levanta la suspensión. No se ha ejecutado ni contabilizado nada.
account_pending_deletion — 403
El propietario del espacio del cliente ha solicitado la eliminación de su cuenta. El espacio deja de actuar: ni por la API, ni por el servidor MCP, ni por sus webhooks, que dejan de enviarse. La solicitud no se anula desde el producto, y las claves se irán con el espacio. No se ha ejecutado ni contabilizado nada.
brand_unavailable — 403
El cliente está limitado a una marca que está en la papelera. Ya no lee ni escribe nada, ni siquiera lo que pertenecía a esa marca: la clave se conserva, y vuelve a funcionar si la marca se restaura. Una marca eliminada definitivamente se lleva sus claves. No se ha ejecutado ni contabilizado nada.
endpoint_shared — 403
PATCH, DELETE o POST …/test sobre un endpoint que cubre todo el espacio, enviado por un cliente limitado a una marca. Un cliente así lista estos endpoints, pero no los modifica, ni los elimina, ni los prueba: eso corresponde a un cliente del espacio, o al panel. No se ha modificado ni enviado nada. Consulta Webhooks.
idempotency_key_required y idempotency_key_too_long — 400
POST /publications o POST /media sin cabecera Idempotency-Key, o con una clave de más de 255 caracteres. No se ha ejecutado nada. Consulta Idempotencia.
idempotency_key_in_flight — 409
Otra petición con la misma clave está en curso. Espera entre uno y unos pocos segundos, y vuelve a enviar la misma petición con la misma clave: recibirás la respuesta de la primera, o este conflicto si todavía no ha terminado. Una reserva cuyo proceso ha desaparecido se recupera al cabo de cinco minutos.
idempotency_key_reused — 409
La clave ya se ha usado, para este cliente, con un cuerpo diferente. Dos casos:
- Has cambiado el contenido conservando la clave: cambia la clave junto con el contenido (
article-42-publie-v2). - Crees que envías el mismo contenido. Busca lo que varía de un envío a otro: una marca de tiempo recalculada, un campo presente una vez de cada dos,
destination_idsen un orden que cambia, una imagen regenerada.
brand_required y brand_not_found — 422
El cliente cubre todo el espacio de trabajo y la escritura no indica a qué marca apunta (brand_required), o designa una marca que no está en su espacio (brand_not_found). Consulta Permisos.
publication_not_publishable — 422
El cuerpo está bien formado, pero la publicación no puede crearse. No se escribe nada.
{
"error": {
"code": "publication_not_publishable",
"message": "The publication date must be in the future.",
"errors": ["The publication date must be in the future."],
"destination_errors": {
"dst_01k4b8x4s1t9j5q7v8y0z2b4d6": ["“Instagram Fabrique” requires an image."]
}
}
}
Errores generales, en errors:
| Mensaje | Causa |
|---|---|
Destination “dst_…” does not belong to this brand. (El destino «dst_…» no pertenece a esta marca.) |
Este identificador no designa ningún destino de la marca: no existe, o depende de otra marca. Los dos casos reciben el mismo mensaje, en el mismo lugar. |
File “med_…” is not available for this brand. (El archivo «med_…» no está disponible para esta marca.) |
Este identificador no designa ningún medio utilizable de la marca: desconocido, de otra marca, eliminado — aunque siga en la papelera —, o todavía no listo. |
A publication must carry a text or an image. (Una publicación debe llevar un texto o una imagen.) |
Ningún destino recibiría ni texto ni imagen. |
Choose a publication date. (Elige una fecha de publicación.) |
mode: "scheduled" sin scheduled_at. |
The publication date must be in the future. (La fecha de publicación debe estar en el futuro.) |
scheduled_at ya ha pasado, al segundo — incluso en modo draft o approval, donde sin embargo no se guarda. |
This brand has reached its monthly publication quota. (Se ha alcanzado la cuota mensual de publicaciones de esta marca.) |
La cuota está consumida hasta el día 1 del mes siguiente. |
Mientras un destino o un medio nombrado no sea de la marca, no se examina ningún destino: corrige primero los identificadores.
Errores de destino, en destination_errors, indexados por identificador:
| Mensaje | Causa |
|---|---|
The connection of “X” must be restored before publishing. (La conexión de «X» debe restablecerse antes de publicar.) |
Destino desactivado, token caducado o conexión que restablecer. Es necesaria una acción en el panel. |
“X” would receive neither text nor image. («X» no recibiría ni texto ni imagen.) |
Las sustituciones de esta red le retiran todo contenido. |
“X” accepts at most N characters; this text has M. («X» acepta N caracteres como máximo; este texto tiene M.) |
Texto demasiado largo para esta red; el mensaje termina en , hashtags included (hashtags incluidos) cuando se le añaden etiquetas. Acórtalo solo ahí con overrides. |
Instagram accepts at most 30 hashtags, those of the text and the tags combined. (Instagram acepta 30 hashtags como máximo, sumando los del texto y las etiquetas.) |
Demasiados hashtags en el pie de foto de Instagram. |
Threads publishes the first tag as a topic, and a topic has at most 50 characters. (Threads publica la primera etiqueta como tema, y un tema tiene 50 caracteres como máximo.) |
Primera etiqueta demasiado larga para un tema de Threads. |
“X” does not publish a first comment. («X» no publica primer comentario.) |
first_comment en sustitución: hoy ninguna red lo publica. |
“X” requires an image. («X» exige una imagen.) |
Instagram o Pinterest sin imagen. |
“X” accepts at most N media. («X» acepta N medio(s) como máximo.) |
Demasiadas imágenes para esta red. |
“X” accepts alternative text of at most 500 characters. («X» acepta un texto alternativo de 500 caracteres como máximo.) |
Texto alternativo demasiado largo para Pinterest. |
Corrige y vuelve a enviar con la misma clave de idempotencia: el fallo la ha liberado.
media_not_acceptable — 422
El archivo no puede convertirse en un medio; nunca ha tocado el disco. error.errors lista los motivos. Convierte la imagen, redúcela y envía el nuevo archivo con una nueva clave: su contenido ha cambiado. Consulta Medios.
transition_not_allowed — 409
El cuerpo es válido; es el estado de la publicación lo que impide la acción solicitada.
| Mensaje | Ruta |
|---|---|
This publication is awaiting approval: a reviewer must approve it before it goes out. (Esta publicación espera una validación: un revisor debe validarla antes de que salga.) |
publish |
This publication is already scheduled. To change when it goes out, move it in the calendar; to stop it, cancel it. (Esta publicación ya está programada. Para cambiar su hora de salida, muévela desde el calendario; para detenerla, cancélala.) |
publish |
This publication has already gone out: it can no longer be published. (Esta publicación ya ha salido: ya no puede publicarse.) |
publish |
This publication has no destination: add one before publishing it. (Esta publicación no tiene ningún destino: añade uno antes de publicarla.) |
publish |
The publication date must be in the future. (La fecha de publicación debe estar en el futuro.) |
publish |
This publication needs N delivery(ies) and only M remain this month. (Esta publicación requiere N entrega(s) y solo quedan M este mes.) |
publish |
This publication is finished: there is nothing left to cancel. (Esta publicación ha terminado: ya no hay nada que cancelar.) |
cancel |
No destination of this publication can be retried. (Ningún destino de esta publicación está pendiente de relanzar.) |
retry |
First restore the connection of “X”: the retry would fail immediately. (Restablece primero la conexión de «X»: el relanzamiento fallaría inmediatamente.) |
retry |
Vuelve a leer la publicación con GET /publications/{id} antes de decidir: un rechazo de transición suele ser la prueba de que la acción ya ha tenido lugar.
endpoint_suspended — 409
POST /webhooks/{id}/test hacia un endpoint suspendido: no recibe nada, y anunciar una prueba enviada sería mentir. Reactiva el endpoint desde el panel y vuelve a probar. Consulta Webhooks.
Códigos del framework
not_found — 404
El identificador no existe, o el recurso pertenece a otra marca o a otro espacio de trabajo. Los dos casos son deliberadamente indistinguibles.
method_not_allowed — 405
La ruta existe, pero no con este verbo. Los endpoints de webhook se modifican con PATCH, no con PUT.
too_many_requests — 429
Se ha superado el límite de frecuencia — el de tu dirección, el de tu cliente, o el de las pruebas de un endpoint de webhook. Consulta Límites y convenciones. Espera el plazo de la cabecera Retry-After. No se ha ejecutado nada, y la clave de idempotencia no se ha reservado: vuelve a enviar la misma petición con la misma clave.
request_failed
Cualquier otro error HTTP lanzado por el framework, sea cual sea su estado: otro 4xx, o un 5xx como 503 durante un mantenimiento. Reintenta un 5xx tras un plazo, no un 4xx.
Fallo — 5xx
{ "message": "Server Error" }
Reintenta con una espera creciente y la misma clave de idempotencia: una respuesta de error libera la clave, y la repetición se ejecutará con normalidad. Es precisamente el caso para el que existe la clave: tú no sabes si la escritura ha tenido lugar, la clave lo sabe. Limita el número de intentos.