Concepts

Erreurs

Les erreurs utilisent les codes de statut HTTP standard et ont toujours la même structure JSON.

Format des erreurs#

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This API key does not have the scope posts:write"
  }
}

code est stable : utilisez-le dans votre code.
message est destiné aux humains et peut changer.
Certaines erreurs ajoutent des champs supplémentaires à côté de code et message (par exemple le champ invalide d'une erreur de validation).

Codes d'erreur#

Statut	Code	Signification · que faire
400	`VALIDATION_ERROR`	Un paramètre ou un champ du corps est manquant ou invalide. Corrigez la requête ; ne la renvoyez pas telle quelle.
400	`INVALID_JSON`	Le corps n'est pas un JSON valide. Envoyez `Content-Type: application/json` et un corps valide.
401	`INVALID_API_KEY`	Clé absente, mal formée ou révoquée. Vérifiez l'en-tête `Authorization`.
403	`INSUFFICIENT_SCOPE`	La clé ne dispose pas du scope requis par cet endpoint. Créez une clé avec les bons scopes.
403	`DEVELOPER_ACCESS_REVOKED`	L'accès développeur de ce compte a été suspendu ou révoqué. Contactez developers@linework.app.
403	`PROFILE_INCOMPLETE`	Ajoutez une photo de profil et une couverture au compte avant d'utiliser les endpoints d'écriture.
403	`CHAT_NOT_ALLOWED`	La règle anti-spam n'autorise pas ce message : la personne ne vous a pas écrit et ne vous suit pas.
403	`CHAT_BLOCKED`	L'un de vous a bloqué l'autre. Ne réessayez pas.
403	`STORE_BLOCKED`	Cette boutique vous a bloqué.
403	`USER_UNAVAILABLE`	L'utilisateur n'est pas disponible (bloqué, privé ou suspendu).
403	`FORBIDDEN`	L'action n'est pas autorisée pour ce compte (par exemple modifier le post de quelqu'un d'autre).
404	`NOT_FOUND`	La ressource n'existe pas ou vous ne pouvez pas la voir.
409	`CONFLICT`	La requête est en conflit avec l'état actuel (par exemple expédier deux fois une commande).
413	`PAYLOAD_TOO_LARGE`	Le corps ou le fichier importé est trop volumineux. Consultez les limites des médias dans Publier avec des médias.
429	`RATE_LIMITED`	Trop de requêtes, ou un quota journalier est épuisé. Attendez le délai indiqué par `Retry-After`. Consultez Limites de débit.
500	`INTERNAL_ERROR`	Un problème est survenu de notre côté. Réessayez plus tard avec un backoff.

De nouveaux codes peuvent être ajoutés au fil du temps : traitez un code inconnu selon la signification générique de son statut HTTP.

Réessayer ou non ?#

Statut	Réessayer ?
400, 401, 403, 404, 409, 413	Non. Corrigez d'abord la requête, la clé ou le compte.
429	Oui, après `Retry-After`.
500, 502, 503, 504	Oui, avec un backoff exponentiel. Pour les écritures non idempotentes (par exemple `POST /posts`), vérifiez d'abord que l'action n'a pas déjà eu lieu.

Exemple de gestionnaire#

const res = await fetch(url, options);
if (!res.ok) {
  const { error } = await res.json().catch(() => ({ error: { code: "UNKNOWN" } }));
  switch (error.code) {
    case "RATE_LIMITED": /* wait Retry-After, then retry */ break;
    case "INVALID_API_KEY":
    case "DEVELOPER_ACCESS_REVOKED": /* stop the bot and alert someone */ break;
    case "CHAT_NOT_ALLOWED": /* skip this user */ break;
    default: throw new Error(`${res.status} ${error.code}: ${error.message}`);
  }
}

r = s.post(url, json=body, timeout=30)  # s = requests.Session() with the Authorization header
if not r.ok:
    err = r.json().get("error", {})
    code = err.get("code")
    if code == "RATE_LIMITED":
        ...  # wait Retry-After, then retry
    elif code in ("INVALID_API_KEY", "DEVELOPER_ACCESS_REVOKED"):
        ...  # stop the bot and alert someone
    elif code == "CHAT_NOT_ALLOWED":
        ...  # skip this user
    else:
        raise RuntimeError(f"{r.status_code} {code}: {err.get('message')}")