- Documentación
- SDK PHP · Versión 0.1
- Errores
Errores
En esta página
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,0cuando 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á enhttps, un filtro desconocido dado apublications()->list(), una llamada awebhooks()->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 deFakeTransportque falla.