Aller au contenu
Quiet Social

Erreurs

Chaque refus de l'API devient une exception nommée, qui répond à la seule question qu'on se pose après un échec : le même appel peut-il réussir s'il est renvoyé ? La méthode isRetryable() y répond, sans avoir à relire la table des statuts HTTP.

La table des exceptions

Toutes vivent dans l'espace de noms QuietSocial\Sdk\Exceptions.

Exception Quand isRetryable()
InvalidPost Le post, une image ou les cibles sont mal formés. Levée avant tout envoi : un défaut du code appelant. Étend InvalidArgumentException, pas SocialException. —
AuthenticationFailed 401 : identifiant inconnu, secret faux ou clé révoquée. non
PermissionDenied 403 : la clé n'a pas le droit qu'exige cet appel. non
PlanRequired 403 plan_required : la clé est valide, mais l'offre de son espace n'inclut pas l'API. La clé est gardée et refonctionne dès que l'espace passe à une offre qui l'inclut. Étend PermissionDenied. non
ResourceNotFound 404 : la ressource n'existe pas pour cette clé. non
ValidationFailed 400 et 422 : l'API refuse ce qui a été envoyé ; 409 autre que ci-dessous (transition_not_allowed, idempotency_key_reused) ; une cible qui ne mène à rien (destination_unavailable, destination_ambiguous). non
RateLimited 429 : trop de requêtes. oui
ServiceUnavailable 5xx, aucune réponse (connection_failed), une réponse illisible (invalid_response), ou 409 idempotency_key_in_flight (la même clé est encore en cours de traitement). oui
SocialException Tout autre refus, comme une image impossible à télécharger (image_download_failed) ou une réponse au-delà de la limite de taille (response_too_large). Parente de toutes les exceptions ci-dessus sauf InvalidPost et InvalidSignature. non
InvalidSignature Une requête de webhook à laquelle on ne peut pas se fier (voir Webhooks). Étend RuntimeException. —

Une image dont l'hôte répond 5xx ou 429 lève une ServiceUnavailable de code image_download_failed : l'obstacle est passager, on peut réessayer.

Ce que porte une exception

Toute SocialException porte :

  • errorCode : le code stable de l'API (publication_not_publishable, transition_not_allowed…), null pour un refus de validation qui n'en a pas. Les codes sont décrits dans Erreurs de la référence de l'API.
  • status : le statut HTTP, 0 quand aucune réponse n'est arrivée ou que le SDK a refusé de lui-même.
  • errors : les erreurs par champ, par nom de champ.

ValidationFailed y ajoute destinationErrors, les raisons du refus de chaque destination, par identifiant de destination. RateLimited y ajoute retryAfterSeconds, lu dans l'en-tête Retry-After (en secondes ou en date HTTP), null quand l'API n'en donne pas.

Réessayer

use QuietSocial\Sdk\Exceptions\RateLimited;
use QuietSocial\Sdk\Exceptions\SocialException;
use QuietSocial\Sdk\Exceptions\ValidationFailed;

try {
    $publication = $client->publications()->create($post, to: ['instagram']);
} catch (ValidationFailed $refus) {
    $refus->errorCode;            // publication_not_publishable, destination_unavailable…
    $refus->errors;               // ['content' => ['…']]
    $refus->destinationErrors;    // ['dst_…' => ['…']]
} catch (SocialException $echec) {
    if (! $echec->isRetryable()) {
        throw $echec;
    }

    $delai = $echec instanceof RateLimited ? ($echec->retryAfterSeconds ?? 60) : 30;

    // Renvoyer le même post après $delai secondes : avec une référence, la clé
    // d'idempotence est la même, et rien n'est publié deux fois.
}

Renvoyer après un échec rejouable n'est sûr qu'avec la même clé d'idempotence : donnez une référence au post (voir Publier). Sans référence, la clé est aléatoire, et un appel arrivé au serveur mais dont la réponse s'est perdue publierait une seconde fois.

Une erreur non rejouable ne se corrige pas en attendant : changez la configuration (clé, droits), le contenu ou les cibles avant de renvoyer.

Les autres exceptions

Quelques erreurs de programmation ne passent pas par SocialException :

  • InvalidArgumentException : une adresse d'API qui n'est pas en https, un filtre inconnu donné à publications()->list(), un appel à webhooks()->update() sans rien à changer, un secret de webhook vide ;
  • LogicException : un client qu'on tente de sérialiser, ou, hors de PHPUnit, une assertion de FakeTransport qui échoue.