Troubleshooting

Install a client and PSR-17 factories, then require the SDK again:

composer require symfony/http-client nyholm/psr7
# or
composer require guzzlehttp/guzzle

Or skip discovery and pass httpClient, requestFactory and streamFactory yourself (Choosing a PSR-18 client). This exception comes from php-http/discovery, not the SDK, so catch (AdobeSignException) doesn't cover it; it happens once at boot.

Upgrade PHP, and check that config.platform.php in your composer.json, if set, says 8.2 or later.

• Integration Key: copy it again from Acrobat Sign (Account → Acrobat Sign API → API Information → Integration Key), with no surrounding spaces or quotes. Check that the user it belongs to is still active.
• OAuth: the SDK already refreshed once and retried. If it still fails, the user's grant is gone; send them through authorization again.
• Don't retry in a loop: a rejected credential stays rejected.

Check that you put() and get() with the same key, and that your store round-trips tokens with AccessToken::toArray() and fromArray() without losing refreshToken. Otherwise, the user has to connect again.

Catch OAuthException, mark the connection as broken, and ask the user to reconnect. To keep dormant connections alive, use them (any call refreshes as needed) within the 60 days.

Keep the state in the user's session from OAuthClient::generateState(), make sure the redirect URI is on the same host as the page that started the flow, and use a session cookie that survives a top-level redirect (SameSite=Lax). Don't skip the check.

If someone tampered with the callback URL, this is the SDK doing its job. If your account genuinely uses another Adobe domain, add it to allowedDomains in OAuthConfig.

Check the address with $sign->users()->all(), and use an Integration Key or OAuth token that belongs to an account administrator.

Check ClientOptions::$bootstrapUrl and any middleware that touches the URI. Clearing the shared cache does no harm. See Rediscovery.

Pass a shared PSR-16 cache (Redis, APCu, files) as cache:. See PSR-16 cache.

Fetch again and repeat, once or twice with a short pause:

try {
    $sign->agreements()->cancel($agreementId, 'Sent in error');
} catch (PreconditionFailedException) {
    sleep(3);
    $sign->agreements()->get($agreementId);                      // remembers the current ETag
    $sign->agreements()->cancel($agreementId, 'Sent in error');
}

If you are on 0.2.0 and see this on a cancel() right after another state change from the same client, upgrade: 0.2.1 fixed a case where the ETag from a state change was reused. How the ETag memory works: ETags and If-Match.

Act as the right user with asUser() (admin token required), or request the missing scope and have the user reconnect.

• Defer the work by $e->retryAfter seconds (a delayed queue job is ideal) rather than retrying immediately.
• Make fewer calls: use webhooks instead of polling status, raise pageSize on lists, share the data-centre cache, and reuse fetched data within a request.
• Move bulk operations to background jobs so a burst doesn't hit user-facing requests.

In web requests, use new ClientOptions(maxRetries: 1, maxRetryDelay: 5.0) and move slow work to jobs. Set a timeout on your PSR-18 client; the SDK sets none. A logger shows which it is: retry warnings, or one request with a long duration_ms.

Nothing is wrong. Poll every couple of seconds until the status changes, or better, subscribe to a webhook and react when the agreement is out for signature. The example scripts poll every 2 seconds, 10 to 15 times.

Wait until the status is OUT_FOR_SIGNATURE, then retry after a few seconds. In a web flow, show "preparing your document" and retry from the browser rather than blocking the request.

Call members($id, includeNextParticipantSet: true), and if the list is empty right after sending, poll again a few seconds later. Each participant set's own status (WAITING_FOR_MY_SIGNATURE, …) is another way to find the current step.

Check the status first, and upgrade if you are on 0.2.0. To remind specific people, pass their participant ids.

Upload again right before creating the agreement. For documents you reuse, create a library document and reference it with FileInfo::libraryDocument().

An Acrobat Sign administrator can enable it in the account's send settings. Until then, use a purely sequential (1, 2, 3) or purely parallel (1, 1, 1) order. Versions before 0.3.0 reported this as a plain ApiException. See Signing order.

Ask an Acrobat Sign administrator to enable the method or feature, or check that your plan includes it. It can't be fixed in code; choosing another method can work around it.

Buy or top up the quota through Adobe, or use another identity check, such as Verification::emailOtp(), for this agreement.

Buy or top up the quota through Adobe. For the identity checks, another method such as Verification::emailOtp() works around it for this agreement.

Ask an Acrobat Sign administrator to allow digital signatures and per-recipient enforcement, with a cloud signature provider configured, or send at SES. See Signature levels.

Expected behaviour. Production accounts don't do this. If you compare names in tests, strip the prefix or compare externalId instead.

Upgrade to 0.3.1 or later, which reads both.

Build agreements with AgreementInfo and set the level there or in ClientOptions; for raw payloads, set isDigitalSignatureRequired: true on each signer set yourself. See Signature levels.

Pass your qualified issuers: $evidence->meets(SignatureLevel::QES, ['DigiCert', 'TrustPro QTSP']). In Laravel, set ADOBE_SIGN_QUALIFIED_ISSUERS.

Set the level only on signer sets, and keep signatureType at ESIGN for digital levels.

Make the URL reachable over HTTPS (a tunnel for local development), allowlist the right client id in WebhookHandler, and return the handler's response unchanged. Test the endpoint first with a curl GET carrying the header (example).

Fix the endpoint first: acknowledge immediately and do slow work on a queue. Then reactivate with $sign->webhooks()->updateState($id, 'ACTIVE'). Notifications from the disabled period are lost, so reconcile by fetching the affected agreements. One webhook per agreement limits the damage from a failure to that agreement.

Allowlist the client id of every application that creates your webhooks (the handler accepts a list). Requests without the header aren't from Adobe.

Store $event->notificationId and skip ones you have seen, and make your processing idempotent (re-fetch the agreement and act on its current status).

Read it once, or call $stream->rewind() first when isSeekable() is true. Write with a chunked loop or detach() as shown in Downloads.

Copy in chunks (read(65536) in a loop) or pass detach() to your storage layer. Also check the PSR-18 client: some buffer whole responses unless configured to stream.