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 inkya_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 two503 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 typebaselayer 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
- Credential Format Reference: every check, in the order it runs.
- KYA Sandbox and Testing: test the full flow with test data.