Aller au contenu
Quiet Social

Erreurs

Cette page répond, pour chaque refus de l'API, à une seule question : faut-il réessayer ?

Réponse Sens
Non La même requête produira la même erreur. Corrigez la configuration, ou abandonnez.
Après correction Corrigez le corps ou l'en-tête, puis renvoyez. La clé d'idempotence reste utilisable.
Oui La cause est passagère. Renvoyez la même requête, après un délai.

Les deux enveloppes

Les refus de l'API portent un code stable dans error.code :

{
  "error": {
    "code": "insufficient_scope",
    "message": "This client does not hold the « destinations:read » scope.",
    "required_ability": "destinations:read"
  }
}

error.code est le contrat : il ne change pas. error.message est écrit pour une personne, et peut être reformulé : ne le comparez jamais.

Les messages de l'API sont en anglais, quelle que soit la langue de votre compte et sans tenir compte de l'en-tête Accept-Language, refus métier compris : règles des brouillons et des réseaux, transitions de publication, adresses de webhook. Exception : l'erreur d'une cible (targets[].error.message) qui ne vient pas de nos règles de publication — refus du réseau à la publication, jeton absent, réseau non configuré, échec technique de la livraison — peut encore être en français, ou dans les mots du réseau lui-même. De même, une cible tombée en échec avant que ces messages soient traduits garde son message en français, dans l'API comme dans les webhooks, tant qu'elle n'est pas relancée. Fiez-vous à error.code et aux clés de errors, jamais au texte. Certains codes portent des champs supplémentaires, décrits plus bas.

Les erreurs de validation de la requête — champ manquant, type faux, valeur hors liste — gardent l'enveloppe de Laravel, sans error.code, avec un statut 422 :

{
  "message": "Send at least one destination.",
  "errors": {
    "destination_ids": ["Send at least one destination."]
  }
}

errors est indexé par nom de champ. Ses messages sont en anglais, comme le reste de l'API.

Refus de forme notables, tous en 422 sur le champ concerné :

  • une date qui n'est pas en ISO 8601 (« The date must follow ISO 8601, for example 2026-10-15T09:00:00+02:00. ») ;
  • media et media_ids envoyés ensemble, ou plus de 10 médias ;
  • plus de 30 tags, ou un tag vide ou trop long une fois mis en forme ;
  • une clé de surcharge qu'un réseau n'admet pas (« « instagram » does not accept: « link_url » »), ou un nom de réseau inconnu ;
  • sur POST /webhooks, une adresse refusée par la garde, un événement hors catalogue, ou un brand_id qui ne désigne aucune marque de l'espace.

Un client robuste lit donc error.code s'il existe, et errors sinon.

$response = $quietSocial->post('/publications', $payload);

if ($response->failed()) {
    $code = $response->json('error.code');          // null pour une erreur de validation
    $fields = $response->json('errors', []);        // présent pour une erreur de validation
}

Table de décision

Code Statut Réessayer ?
unauthenticated 401 Non
insufficient_scope 403 Non
plan_required 403 Après un changement d'offre
workspace_suspended 403 Après la levée de la suspension
account_pending_deletion 403 Non
brand_unavailable 403 Après la restauration de la marque
endpoint_shared 403 Non
idempotency_key_required 400 Après correction
idempotency_key_too_long 400 Après correction
idempotency_key_in_flight 409 Oui
idempotency_key_reused 409 Non, pas avec cette clé
brand_required 422 Après correction
brand_not_found 422 Après correction
publication_not_publishable 422 Après correction
media_not_acceptable 422 Non, pas avec ce fichier
transition_not_allowed 409 Non
endpoint_suspended 409 Après réactivation
not_found 404 Non
method_not_allowed 405 Non
too_many_requests 429 Oui, après un délai
request_failed tout autre statut 4xx : non ; 5xx : oui
(validation, sans code) 422 Après correction
(panne, sans code) 5xx Oui

Codes de l'API

unauthenticated — 401

Identifiants absents, illisibles, inconnus, faux, ou client révoqué. Vérifiez que l'identifiant qsc_… est envoyé comme nom d'utilisateur et le secret qss_… comme mot de passe. Voir Authentification.

insufficient_scope — 403

Le client est authentifié mais n'a pas le périmètre exigé par la route. error.required_ability nomme le périmètre à faire accorder. GET /me liste d'un coup ceux que vous avez.

plan_required — 403

Le client est valide, mais l'offre de son espace n'inclut pas l'API (Gratuit et Solo). La clé est gardée : elle refonctionne dès que l'espace passe à Studio ou au-delà.

workspace_suspended — 403

L'espace du client est suspendu par l'Éditeur, qui en a envoyé le motif à son propriétaire. La clé est gardée : elle refonctionne à la levée de la suspension. Rien n'a été exécuté ni compté.

account_pending_deletion — 403

Le propriétaire de l'espace du client a demandé la suppression de son compte. L'espace n'agit plus : ni par l'API, ni par le serveur MCP, ni par ses webhooks, qui cessent d'être envoyés. La demande ne s'annule pas depuis le produit, et les clés partiront avec l'espace. Rien n'a été exécuté ni compté.

brand_unavailable — 403

Le client est borné à une marque qui est à la corbeille. Il ne lit ni n'écrit plus rien, même ce qui relevait de cette marque : la clé est gardée, et refonctionne si la marque est restaurée. Une marque effacée définitivement emporte ses clés. Rien n'a été exécuté ni compté.

endpoint_shared — 403

PATCH, DELETE ou POST …/test sur un endpoint qui couvre tout l'espace, envoyé par un client borné à une marque. Un tel client liste ces endpoints, mais ne les modifie, ne les supprime ni ne les teste : c'est l'affaire d'un client de l'espace, ou du tableau de bord. Rien n'a été modifié ni envoyé. Voir Webhooks.

idempotency_key_required et idempotency_key_too_long — 400

POST /publications ou POST /media sans en-tête Idempotency-Key, ou avec une clé de plus de 255 caractères. Rien n'a été exécuté. Voir Idempotence.

idempotency_key_in_flight — 409

Une autre requête portant la même clé est en cours. Attendez une à quelques secondes, puis renvoyez la même requête avec la même clé : vous recevrez la réponse de la première, ou ce conflit si elle n'est pas finie. Une réservation dont le processus a disparu est reprise au bout de cinq minutes.

idempotency_key_reused — 409

La clé a déjà servi, pour ce client, avec un corps différent. Deux cas :

  1. Vous avez changé le contenu en gardant la clé : changez la clé avec le contenu (article-42-publie-v2).
  2. Vous croyez envoyer le même contenu. Cherchez ce qui varie d'un envoi à l'autre : un horodatage recalculé, un champ présent une fois sur deux, destination_ids dans un ordre qui change, une image régénérée.

brand_required et brand_not_found — 422

Le client couvre tout l'espace de travail et l'écriture ne dit pas quelle marque viser (brand_required), ou désigne une marque qui n'est pas dans son espace (brand_not_found). Voir Périmètres.

publication_not_publishable — 422

Le corps est bien formé, mais la publication ne peut pas être créée. Rien n'est écrit.

{
  "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."]
    }
  }
}

Erreurs générales, dans errors :

Message Cause
Destination “dst_…” does not belong to this brand. (La destination « dst_… » n'appartient pas à cette marque.) Cet identifiant ne désigne aucune destination de la marque : il n'existe pas, ou il relève d'une autre marque. Les deux cas reçoivent le même message, au même endroit.
File “med_…” is not available for this brand. (Le fichier « med_… » n'est pas disponible pour cette marque.) Cet identifiant ne désigne aucun média utilisable de la marque : inconnu, d'une autre marque, supprimé — même encore dans la corbeille —, ou pas encore prêt.
A publication must carry a text or an image. (Une publication doit porter un texte ou une image.) Aucune destination ne recevrait ni texte ni image.
Choose a publication date. (Choisissez une date de publication.) mode: "scheduled" sans scheduled_at.
The publication date must be in the future. (La date de publication doit être dans le futur.) scheduled_at est passée, à la seconde près — y compris en mode draft ou approval, où elle n'est pourtant pas enregistrée.
This brand has reached its monthly publication quota. (Le quota mensuel de publications de cette marque est atteint.) Le quota est consommé jusqu'au premier du mois suivant.

Tant qu'une destination ou un média nommé n'est pas à la marque, aucune destination n'est examinée : corrigez d'abord les identifiants.

Erreurs de destination, dans destination_errors, indexées par identifiant :

Message Cause
The connection of “X” must be restored before publishing. (La connexion de « X » doit être rétablie avant de publier.) Destination désactivée, jeton expiré ou connexion à rétablir. Une action dans le tableau de bord est nécessaire.
“X” would receive neither text nor image. (« X » ne recevrait ni texte ni image.) Les surcharges de ce réseau lui retirent tout contenu.
“X” accepts at most N characters; this text has M. (« X » accepte N caractères au maximum ; ce texte en compte M.) Texte trop long pour ce réseau ; le message finit par , hashtags included (hashtags compris) quand des tags s'y ajoutent. Raccourcissez-le là seulement avec overrides.
Instagram accepts at most 30 hashtags, those of the text and the tags combined. (Instagram accepte 30 hashtags au maximum, ceux du texte et les tags confondus.) Trop de hashtags dans la légende Instagram.
Threads publishes the first tag as a topic, and a topic has at most 50 characters. (Threads publie le premier tag comme sujet, et un sujet compte 50 caractères au maximum.) Premier tag trop long pour un sujet Threads.
“X” does not publish a first comment. (« X » ne publie pas de premier commentaire.) first_comment en surcharge : aucun réseau ne le publie aujourd'hui.
“X” requires an image. (« X » exige une image.) Instagram ou Pinterest sans image.
“X” accepts at most N media. (« X » accepte N média(s) au maximum.) Trop d'images pour ce réseau.
“X” accepts alternative text of at most 500 characters. (« X » accepte un texte alternatif de 500 caractères au maximum.) Texte alternatif trop long pour Pinterest.

Corrigez, puis renvoyez avec la même clé d'idempotence : l'échec l'a libérée.

media_not_acceptable — 422

Le fichier ne peut pas devenir un média ; il n'a jamais touché le disque. error.errors liste les motifs. Convertissez l'image, réduisez-la, puis envoyez le nouveau fichier avec une nouvelle clé : son contenu a changé. Voir Médias.

transition_not_allowed — 409

Le corps est valide, c'est l'état de la publication qui s'oppose à l'action demandée.

Message Route
This publication is awaiting approval: a reviewer must approve it before it goes out. (Cette publication attend une validation : un relecteur doit la valider avant qu'elle parte.) publish
This publication is already scheduled. To change when it goes out, move it in the calendar; to stop it, cancel it. (Cette publication est déjà programmée. Pour changer son heure de départ, déplacez-la depuis le calendrier ; pour l'arrêter, annulez-la.) publish
This publication has already gone out: it can no longer be published. (Cette publication est déjà partie : elle ne peut plus être publiée.) publish
This publication has no destination: add one before publishing it. (Cette publication n'a aucune destination : ajoutez-en une avant de la publier.) publish
The publication date must be in the future. (La date de publication doit être dans le futur.) publish
This publication needs N delivery(ies) and only M remain this month. (Cette publication demande N livraison(s) et il n'en reste que M ce mois-ci.) publish
This publication is finished: there is nothing left to cancel. (Cette publication est terminée : il n'y a plus rien à annuler.) cancel
No destination of this publication can be retried. (Aucune destination de cette publication n'est à relancer.) retry
First restore the connection of “X”: the retry would fail immediately. (Rétablissez d'abord la connexion de « X » : la relance échouerait immédiatement.) retry

Relisez la publication avec GET /publications/{id} avant de décider : un refus de transition est souvent la preuve que l'action a déjà eu lieu.

endpoint_suspended — 409

POST /webhooks/{id}/test vers un endpoint suspendu : il ne reçoit rien, et annoncer un test envoyé mentirait. Réactivez l'endpoint depuis le tableau de bord, puis testez de nouveau. Voir Webhooks.

Codes du framework

not_found — 404

L'identifiant n'existe pas, ou la ressource appartient à une autre marque ou à un autre espace de travail. Les deux cas sont volontairement indiscernables.

method_not_allowed — 405

Le chemin existe, pas avec ce verbe. Les endpoints de webhook se modifient en PATCH, pas en PUT.

too_many_requests — 429

La limite de débit est dépassée — celle de votre adresse, celle de votre client, ou celle des tests d'un endpoint de webhook. Voir Limites et conventions. Attendez le délai de l'en-tête Retry-After. Rien n'a été exécuté, et la clé d'idempotence n'a pas été réservée : renvoyez la même requête avec la même clé.

request_failed

Toute autre erreur HTTP levée par le framework, quel que soit son statut : un autre 4xx, ou un 5xx comme 503 pendant une maintenance. Réessayez un 5xx après un délai, pas un 4xx.

Panne — 5xx

{ "message": "Server Error" }

Réessayez avec une temporisation croissante et la même clé d'idempotence : une réponse en erreur libère la clé, et le rejeu s'exécutera normalement. C'est précisément le cas pour lequel la clé existe : vous ne savez pas si l'écriture a eu lieu, la clé le sait. Plafonnez le nombre de tentatives.