Ir al contenido
Quiet Social

Errores

Esta documentación está traducida del francés. Si ambas versiones difieren, prevalece la versión francesa.

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);
  • media y media_ids enviados 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 un brand_id que 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:

  1. Has cambiado el contenido conservando la clave: cambia la clave junto con el contenido (article-42-publie-v2).
  2. 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_ids en 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.