- Documentation
- API · Version 1.0
- Erreurs
Erreurs
Sur cette page
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. ») ;
mediaetmedia_idsenvoyé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 unbrand_idqui 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 :
- Vous avez changé le contenu en gardant la clé : changez la clé avec le contenu (
article-42-publie-v2). - 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_idsdans 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.