Errors & exceptions

The hierarchy

Every exception implements Conceptlz\AdobeSign\Exception\AdobeSignException, so one catch covers everything the SDK throws. Below it, exceptions fall into four families: errors the API returned, input rejected before sending, requests that never got a response, and rejected inbound webhooks.

Exception reference

How a response becomes an exception

When Adobe answers with anything other than 2xx or 304, an internal ErrorMapper picks the exception class. It is marked @internal, so you won't call it yourself, but knowing its rules tells you exactly what to catch.

1. Read the error body

   Adobe normally sends {"code": "INVALID_AGREEMENT_ID", "message": "…"}. The spec's examples also use {"reason": "INVALID_AGREEMENT_ID: …"}, and the OAuth endpoints use {"error": "…", "error_description": "…"}; all three are understood. A body that isn't JSON becomes the message, cut to 200 characters.

2. Look up the Adobe error code

   If the code is in the SDK's table, that decides the class, whatever the HTTP status. INVALID_X_API_USER_HEADER arrives as a 400 but is an AuthenticationException, because it is an authentication problem. Likewise DYNAMIC_DOCUMENT_EXPIRATION_NOT_ENABLED arrives as a 412 but is an AccountCapabilityException: no fresh ETag would make it succeed.

3. Fall back to the HTTP status

   An unknown or missing code is mapped by status: 400 and 415 to ValidationException, 401 to AuthenticationException, 404 to NotFoundException, 412 to PreconditionFailedException, 429 to RateLimitException. Every other status gives a plain ApiException.

4. Check for an account restriction

   If the result so far is ValidationException and the message says something like "not allowed by account settings", "enabled for your account" or "not enabled for this account", the class becomes AccountCapabilityException. Adobe reports some account limits only as a generic BAD_REQUEST, and the wording is the only way to tell them from bad input.

The message always has the same shape, so logs are easy to search:

GET /api/rest/v6/agreements/CBJCHBCAABAAbad failed with HTTP 404 [INVALID_AGREEMENT_ID]: The Agreement ID specified is invalid.
PUT /api/rest/v6/agreements/CBJCHBCAABAAx1aF…/state failed with HTTP 412 [RESOURCE_MODIFIED]: Resource is already modified with newer version.

What happens before the mapper

Two errors get one automatic second chance first, and two kinds of retries happen even earlier, in the middleware:

• A 401 makes the token provider invalidate its token. If it then has a different token (OAuth refresh), the request is repeated once.
• A 403 INVALID_API_ACCESS_POINT makes the SDK rediscover the data centre and repeat the request once.
• 429 and 503 are retried by RetryMiddleware up to maxRetries times before the mapper ever sees them.

Only when those are exhausted do you get an exception. Details are on Data centres, retries & ETags.

Properties on API exceptions

ApiException and its subclasses carry everything you need to log, report or decide what to do next:

TransportException is simpler: a message and, through getPrevious(), the PSR-18 client's own exception. InvalidArgumentException and WebhookException carry only a message.

use Conceptlz\AdobeSign\Exception\ApiException;

try {
    $sign->agreements()->create($info);
} catch (ApiException $e) {
    $logger->error('Adobe Sign rejected the agreement', [
        'status' => $e->statusCode,
        'code' => $e->errorCode,
        'message' => $e->getMessage(),
        'body' => (string) $e->response?->getBody(),   // Adobe's JSON, for support tickets
    ]);
    throw $e;
}

Credentials never end up in exceptions

Exceptions get logged, dumped in error pages and sent to error trackers, so the SDK makes sure they can't carry a secret:

• The bearer token is replaced. ApiException's constructor swaps the Authorization header on the stored request for Bearer ***, whoever builds the exception. ApiException::redact() does the same for any request you hold.
• OAuth request bodies are dropped. Token, refresh and revoke requests carry the client secret, the code or the refresh token in their body, so an OAuthException keeps the request without it.
• Keys stay out of dumps. IntegrationKeyTokenProvider, OAuthConfig and AccessToken mask their secrets in var_dump(), and secret parameters are marked #[\SensitiveParameter], so they don't appear in stack traces.
• The logger never receives headers or bodies (PSR-3 logging).

The test suite enforces this (CredentialSafetyTest, plus a check in the live suite that a real error's request reads Bearer ***). What remains in an exception is ordinary business data: resource ids in the path, and Adobe's error body in $response.

Adobe error codes and the exception you get

The left-hand column is the value of $e->errorCode. "By code" means the SDK maps that code explicitly; "by status" means it falls back to the HTTP status Adobe normally sends with it.

A code that isn't in this table still reaches you in $e->errorCode; only the class is chosen by status. Adobe adds codes over time, so compare errorCode strings rather than relying on a closed list.

Recommended catch patterns

At the edge: catch the interface

In a controller or command, one catch (AdobeSignException $e) is enough to turn any SDK failure into a friendly message. It covers local validation, network failures and API errors alike.

use Conceptlz\AdobeSign\Exception\AdobeSignException;

try {
    $agreementId = $contracts->send($contract);
} catch (AdobeSignException $e) {
    $logger->error($e->getMessage(), ['exception' => $e]);
    $flash->error('We could not send the contract for signature. Please try again shortly.');
}

Specific types first

PHP uses the first matching catch, so order matters: subclasses before parents.

use Conceptlz\AdobeSign\Exception\{
    AccountCapabilityException, AdobeSignException, AuthenticationException, NotFoundException,
    OAuthException, PreconditionFailedException, RateLimitException, TransportException,
};

try {
    $sign->agreements()->cancel($agreementId, 'Replaced by a new version');
} catch (OAuthException $e) {
    $user->markAdobeSignDisconnected();                // must come before AuthenticationException
} catch (AuthenticationException $e) {
    $alerts->page('Adobe Sign credentials rejected: ' . $e->errorCode);
} catch (NotFoundException $e) {
    // already deleted, or never existed for this user: nothing to cancel
} catch (PreconditionFailedException $e) {
    $sign->agreements()->get($agreementId);           // fresh ETag
    $sign->agreements()->cancel($agreementId, 'Replaced by a new version');
} catch (RateLimitException | TransportException $e) {
    throw $e;                                         // let the queue retry the job
} catch (AccountCapabilityException $e) {
    $admins->notify("Acrobat Sign account setting needed: {$e->errorCode}");
} catch (AdobeSignException $e) {
    $logger->error($e->getMessage(), ['exception' => $e]);
}

In queue jobs: retryable or not

A background job should retry what can succeed later and fail fast on what can't. This helper encodes that split:

use Conceptlz\AdobeSign\Exception\{ApiException, PreconditionFailedException, RateLimitException, TransportException};

function isWorthRetrying(\Throwable $e): bool
{
    return $e instanceof RateLimitException
        || $e instanceof TransportException
        || $e instanceof PreconditionFailedException   // only if the job calls get() before writing
        || ($e instanceof ApiException && $e->statusCode >= 500)
        || ($e instanceof ApiException && in_array($e->errorCode, ['AGREEMENT_NOT_EXPOSED', 'AGREEMENT_NOT_SIGNABLE'], true));
}

Everything else (authentication, validation, account capability, a 404 for a deleted agreement) needs a person to change something, and retrying only adds load.

Branching on the Adobe code

The class tells you the kind of failure; errorCode tells you the exact one. Branch on it when two failures of the same class need different handling:

try {
    $url = $sign->agreements()->signingUrlFor($agreementId, $signerEmail);
} catch (NotFoundException $e) {
    $url = match ($e->errorCode) {
        'AGREEMENT_NOT_EXPOSED', 'AGREEMENT_NOT_SIGNABLE' => null,   // still processing: show "try again"
        default => throw $e,
    };
}

Errors raised before any request

InvalidArgumentException means the SDK refused to send something it knows Adobe would reject, or that would be unsafe. Nothing reached the network. Common causes:

• An empty resource id, or an empty asUser() argument.
• An AgreementInfo with no file or no participant set, or signing orders with a gap (1, 3).
• AES or QES asked of an approver or other non-signing role, or combined with written signatures.
• An upload from a path that can't be read, or from a stream without a file name.
• signingUrls() with an expiry outside 30 to 315360000 seconds.
• A QES check (meets() or shortfalls()) without a list of qualified issuers.
• An OAuth api_access_point that isn't HTTPS on an allowed domain.
• A payload that can't be encoded as JSON (invalid UTF-8, for example).

It extends PHP's own \InvalidArgumentException, so existing handlers for that type catch it too.

Webhook errors

WebhookHandler::verifyClientId() and parse() throw WebhookException for a missing or unknown X-AdobeSign-ClientId header, or a body that isn't a JSON notification. handle() never throws for a bad request: it returns a WebhookResult with the exception in $error and a response with the right status (403 for an unknown client, 400 for an unreadable body, 405 for another method). See Webhooks.

Common questions

• TroubleshootingSymptom, cause and fix for the errors people actually hit.
• Data centres, retries & ETagsThe retries and second chances that happen before an exception.
• Testing your integrationQueue error responses and assert on the exceptions.