Skip to content
Quiet Social

Errors

This documentation is translated from French. Should the two versions differ, the French version prevails.

Every refusal of the API becomes a named exception, which answers the only question asked after a failure: can the same call succeed if it is sent again? The isRetryable() method answers it, without having to read the table of HTTP statuses again.

The exception table

They all live in the QuietSocial\Sdk\Exceptions namespace.

Exception When isRetryable()
InvalidPost The post, an image or the targets are malformed. Thrown before anything is sent: a bug in the calling code. Extends InvalidArgumentException, not SocialException. —
AuthenticationFailed 401: unknown identifier, wrong secret or revoked key. no
PermissionDenied 403: the key lacks the right this call needs. no
PlanRequired 403 plan_required: the key is valid, but the plan of its workspace does not include the API. The key is kept and works again as soon as the workspace moves to a plan that includes it. Extends PermissionDenied. no
ResourceNotFound 404: the resource does not exist for this key. no
ValidationFailed 400 and 422: the API refused what was sent; 409 other than below (transition_not_allowed, idempotency_key_reused); a target that leads nowhere (destination_unavailable, destination_ambiguous). no
RateLimited 429: too many requests. yes
ServiceUnavailable 5xx, no response at all (connection_failed), an unreadable answer (invalid_response), or 409 idempotency_key_in_flight (the same key is still being processed). yes
SocialException Any other refusal, such as an image that cannot be downloaded (image_download_failed) or a response over the size limit (response_too_large). The parent of every exception above but InvalidPost and InvalidSignature. no
InvalidSignature A webhook request that cannot be trusted (see Webhooks). Extends RuntimeException. —

An image whose host answers 5xx or 429 throws a ServiceUnavailable with the code image_download_failed: the obstacle is temporary, the call can be retried.

What an exception carries

Every SocialException carries:

  • errorCode: the stable code of the API (publication_not_publishable, transition_not_allowed…), null for a validation refusal without one. The codes are described in Errors of the API reference.
  • status: the HTTP status, 0 when no response was received or the SDK refused by itself.
  • errors: the field errors, keyed by field name.

ValidationFailed adds destinationErrors, the reasons each destination refused, keyed by destination id. RateLimited adds retryAfterSeconds, read from the Retry-After header (in seconds or as an HTTP date), null when the API gave none.

Retrying

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

    $delay = $failure instanceof RateLimited ? ($failure->retryAfterSeconds ?? 60) : 30;

    // Send the same post again after $delay seconds: with a reference, the
    // idempotency key is the same, and nothing is published twice.
}

Sending again after a retryable failure is safe only with the same idempotency key: give the post a reference (see Publishing). Without a reference, the key is random, and a call that reached the server but whose answer was lost would publish a second time.

A failure that is not retryable is not fixed by waiting: change the configuration (key, rights), the content or the targets before sending again.

Other exceptions

A few programming errors do not go through SocialException:

  • InvalidArgumentException: an API address that is not https, an unknown filter given to publications()->list(), a call to webhooks()->update() with nothing to change, an empty webhook secret;
  • LogicException: an attempt to serialize a client or, outside PHPUnit, a failing assertion of FakeTransport.