Skip to main content
When a credential check fails, it fails with one code, a lowercase string such as audience_mismatch. The Credential Format Reference lists the checks in the order they run, and Agent Acceptance reports the same code on a refused credential. Only two credential 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. Agents treat any 5xx as worth retrying and any 4xx as final.

Your Application Creates the Response

Your own route logic produces these two before it checks a credential.

Try Again Later

These are the only two 503 cases. 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. Never accept a credential you couldn’t check.

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.

Refuse and Investigate

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

Credential Refusals in Agent Acceptance

With Agent Acceptance on, a refused credential is also reported on the request’s decision, as an attestation of type baselayer with status invalid. Its failure_reason is the same code, such as audience_not_registered. See Attestations.

Acceptance Errors

These come from Baselayer’s acceptance API when you change your settings or read activity, not from the credential check.

Next Steps