Troubleshooting: issuance
The transaction is stuck in awaiting_wallet
It is not stuck. awaiting_wallet means the offer exists and the holder has not accepted it yet.
Accepting happens in the holder's wallet and cannot be driven from your server. Until it happens, this is the correct state.
Check: did the holder actually receive the offer? A QR code that was never displayed, or a link that never reached them, produces exactly this state indefinitely.
Offers expire. If one lapses, create a new issuance.
I retried and got the same transaction
That is idempotency working. The same Idempotency-Key with the same payload replays the original result
rather than creating a second credential.
If you wanted a genuinely new issuance, use a new key.
409 on retry
The same Idempotency-Key was reused with a different payload.
Usually a bug in how the key is derived — two different operations assigned the same key. Failing loudly is deliberate: silently returning the first result would send the wrong credential to the wrong person.
Check that your key comes from the business identifier of the specific operation.
Every retry creates a new transaction
You are generating a fresh key per attempt. The key must be created once, before the first attempt, and reused for every retry. See use idempotency.
400 on a claim
The claim is not declared in the credential configuration, or a required one is missing. error.target names
it.
Adding a claim to a configuration is possible; check whether the configuration you are naming is the one you think it is.
404 on the issuer
Wrong environment, or the issuer belongs to another tenant. A cross-environment or cross-tenant reference reports as not found rather than forbidden.
Timed out — did it work?
Retry with the same Idempotency-Key. You get the original result if it succeeded, and a fresh attempt if
it did not. That is what the header is for.