Ir al contenido
Quiet Social

Errores

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

Cada rechazo de la API se convierte en una excepción con nombre, que responde a la única pregunta que uno se hace tras un fallo: ¿puede tener éxito la misma llamada si se reenvía? El método isRetryable() lo responde, sin tener que releer la tabla de estados HTTP.

La tabla de excepciones

Todas viven en el espacio de nombres QuietSocial\Sdk\Exceptions.

Excepción Cuándo isRetryable()
InvalidPost El post, una imagen o los destinos están mal formados. Se lanza antes de enviar nada: un fallo del código que llama. Extiende InvalidArgumentException, no SocialException. —
AuthenticationFailed 401: identificador desconocido, secreto incorrecto o clave revocada. no
PermissionDenied 403: la clave no tiene el permiso que exige esta llamada. no
PlanRequired 403 plan_required: la clave es válida, pero el plan de su espacio no incluye la API. La clave se conserva y vuelve a funcionar en cuanto el espacio pasa a un plan que la incluye. Extiende PermissionDenied. no
ResourceNotFound 404: el recurso no existe para esta clave. no
ValidationFailed 400 y 422: la API rechaza lo que se envió; 409 distinto del de abajo (transition_not_allowed, idempotency_key_reused); un destino que no lleva a ninguna parte (destination_unavailable, destination_ambiguous). no
RateLimited 429: demasiadas peticiones. sí
ServiceUnavailable 5xx, ninguna respuesta (connection_failed), una respuesta ilegible (invalid_response), o 409 idempotency_key_in_flight (la misma clave se está procesando todavía). sí
SocialException Cualquier otro rechazo, como una imagen imposible de descargar (image_download_failed) o una respuesta que supera el límite de tamaño (response_too_large). Madre de todas las excepciones de arriba salvo InvalidPost e InvalidSignature. no
InvalidSignature Una petición de webhook de la que no se puede fiar (ver Webhooks). Extiende RuntimeException. —

Una imagen cuyo host responde 5xx o 429 lanza una ServiceUnavailable con el código image_download_failed: el obstáculo es pasajero, se puede reintentar.

Lo que lleva una excepción

Toda SocialException lleva:

  • errorCode: el código estable de la API (publication_not_publishable, transition_not_allowed…), null para un rechazo de validación que no lo tiene. Los códigos se describen en Errores de la referencia de la API.
  • status: el estado HTTP, 0 cuando no llegó ninguna respuesta o el SDK rechazó por sí mismo.
  • errors: los errores por campo, por nombre de campo.

ValidationFailed añade destinationErrors, los motivos del rechazo de cada destino, por identificador de destino. RateLimited añade retryAfterSeconds, leído en la cabecera Retry-After (en segundos o como fecha HTTP), null cuando la API no da ninguno.

Reintentar

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 $rechazo) {
    $rechazo->errorCode;          // publication_not_publishable, destination_unavailable…
    $rechazo->errors;             // ['content' => ['…']]
    $rechazo->destinationErrors;  // ['dst_…' => ['…']]
} catch (SocialException $fallo) {
    if (! $fallo->isRetryable()) {
        throw $fallo;
    }

    $espera = $fallo instanceof RateLimited ? ($fallo->retryAfterSeconds ?? 60) : 30;

    // Reenviar el mismo post tras $espera segundos: con una referencia, la clave
    // de idempotencia es la misma, y nada se publica dos veces.
}

Reenviar tras un fallo reintentable solo es seguro con la misma clave de idempotencia: da una referencia al post (ver Publicar). Sin referencia, la clave es aleatoria, y una llamada que llegó al servidor pero cuya respuesta se perdió publicaría por segunda vez.

Un fallo que no es reintentable no se arregla esperando: cambia la configuración (clave, permisos), el contenido o los destinos antes de reenviar.

Las demás excepciones

Algunos errores de programación no pasan por SocialException:

  • InvalidArgumentException: una dirección de API que no está en https, un filtro desconocido dado a publications()->list(), una llamada a webhooks()->update() sin nada que cambiar, un secreto de webhook vacío;
  • LogicException: un intento de serializar un cliente o, fuera de PHPUnit, una aserción de FakeTransport que falla.