Handling Failures

The KYA SDK is coming soon. The packages aren’t published yet, so the helpers named here won’t run until they are.

When a check fails, report.failure holds one VerificationFailure code and report.checks shows every check that ran. The code is the same string in TypeScript and Python. Only two failures are retryable. Both mean Baselayer couldn’t be reached from your side, not that anything is wrong with the credential. Every other failure is final: the same presentation will fail again.

Responding to the agent

Put the code in kya_error in the JSON body so the agent can tell what went wrong. The agent side of the SDK reads it from there. toOAuthError(failure) (failure.to_oauth_error() in Python) builds the whole answer for you.

Kind	HTTP status	`error`
Retryable	`503`	none
`UNKNOWN_DISCLOSURE_SCOPE`	`400`	`invalid_scope`
Every other failure	`400`	`invalid_request`

The agent side treats any 5xx as worth retrying and any 4xx as final. The oauthError helper in the SDK quickstart follows this table.

Your application creates the response

verify never returns these two. Your own route logic produces them before it calls verify.

Code	Meaning	Action
`NO_CREDENTIAL_PRESENTED`	The request had no credential.	Respond `401` with your `KYA-Disclosure-Scope` header so the agent knows what to present.
`UNKNOWN_DISCLOSURE_SCOPE`	The scope the agent sent isn’t in your published profile.	Check that your `kya-profile.json` is published and the agent used a scope from it.

Try again later

These are the only two 503 cases. Nothing is wrong with the credential. Your server couldn’t fetch one of Baselayer’s public files. You choose whether to fail open or closed. If you fail closed, return 503 so the agent tries again later. You can pass a Retry-After time in seconds as the second argument to toOAuthError (retry_after in Python).

Code	Meaning	Action
`ISSUER_RESOLUTION_FAILED`	Baselayer’s signing keys couldn’t be fetched.	Fail open, or return `503`.
`STATUS_LIST_RESOLUTION_FAILED`	Baselayer’s revocation list couldn’t be fetched.	Fail open, or return `503`.

Present a corrected or fresh credential

These are final for this presentation. The agent or its builder can often fix the input and present again.

Code	Meaning	Action
`MALFORMED_PRESENTATION`	The credential couldn’t be read.	Tell the agent the credential is malformed.
`UNSUPPORTED_CREDENTIAL_TYPE`	This isn’t a KYA credential type the SDK accepts.	Tell the agent to present a KYA credential.
`SANDBOX_ISSUER`	A sandbox (test) credential, and sandbox credentials are off.	In testing, turn on `allowSandbox`. In production, refuse.
`CREDENTIAL_EXPIRED`	The credential has expired.	Tell the agent to present a fresh credential.
`CREDENTIAL_NOT_YET_VALID`	The credential’s start time is in the future.	Tell the agent to present a valid credential. If this happens often, check your server clock.
`KEY_BINDING_MISSING`	The agent didn’t sign the presentation.	Tell the agent to sign with its key and your nonce.
`KEY_BINDING_INVALID`	The agent’s signature is wrong, or doesn’t cover this presentation. On a business pair, the two credentials use different keys or nonces.	Tell the agent to fetch a new nonce and present again.
`NONCE_NOT_ISSUED`	You never issued this nonce, or it expired (10 minutes by default).	Tell the agent to fetch a new nonce. On many servers, check that they share one `NonceStore`.
`NONCE_REPLAYED`	This nonce was already used.	Tell the agent to fetch a new nonce. If you didn’t expect a second use, this may be a replay.
`AUDIENCE_MISMATCH`	The credential was issued for another site, or signed for another audience.	Check that your verifier’s `audience` is your domain exactly as credentials are minted for you. Otherwise refuse.
`ACTOR_MISMATCH`	The business and person credentials don’t belong together, or a business L3 credential came without its person.	Tell the agent to present the business credential with the acting person’s credential.
`SCOPE_VIOLATION`	The credential shares fields outside the scope you asked for. The whole credential is refused.	Tell the agent to get a credential minted for exactly that scope.

Refuse and investigate

These point to a credential that can’t be trusted. Refuse, and log the failure with its checks.

Code	Meaning	Action
`UNTRUSTED_ISSUER`	Baselayer didn’t issue this credential.	Refuse.
`UNKNOWN_SIGNING_KEY`	The credential names a signing key Baselayer doesn’t publish.	Refuse.
`ISSUER_SIGNATURE_INVALID`	The signature doesn’t match. The credential was changed or forged.	Refuse.
`STATUS_LIST_INVALID`	The revocation list couldn’t be trusted.	Refuse.
`CREDENTIAL_REVOKED`	The credential has been revoked.	Refuse. Treat it the same as an expired credential.
`UNSUPPORTED_DIGEST_ALGORITHM`	The credential uses a hashing method the SDK doesn’t accept.	Refuse.
`DISCLOSURE_DIGEST_MISMATCH`	A shared field doesn’t match what Baselayer signed. A value was changed.	Refuse.
`ACTOR_NOT_AUTHORIZED`	Baselayer hasn’t verified that this person may act for the business.	Refuse.
`VERIFICATION_LEVEL_MISMATCH`	The credential’s verification summary does not match the checks it lists.	Refuse.

Using the checks list

report.checks lists every check that ran with a name, whether it passed and a short detail. Log it with the failure. It shows exactly where a credential stopped, which helps when an agent builder asks why they were refused.

Next steps

Start in watch-only mode: verify and log every credential before you change anyone’s access.
KYA Sandbox and Testing: test the full flow with test data.

GET STARTED

KEY CONCEPTS

PLAYBOOKS

PRODUCT GUIDES

INTEGRATIONS

Responding to the agent

Your application creates the response

Try again later

Present a corrected or fresh credential

Refuse and investigate

Using the checks list

Next steps

​Responding to the agent

​Your application creates the response

​Try again later

​Present a corrected or fresh credential

​Refuse and investigate

​Using the checks list

​Next steps

Responding to the agent

Your application creates the response

Try again later

Present a corrected or fresh credential

Refuse and investigate

Using the checks list

Next steps