Caller credential error codes

POST /api/v1/apps/converse returns 202 Accepted before the turn executes. If a tool later refuses because caller authority is unavailable, the session stream emits a structured event so your application can recover without interpreting the assistant's natural-language response.

{
  "v": 1,
  "sessionId": "40b9779d-…",
  "seq": 4,
  "ts": "2026-08-02T14:30:00.000Z",
  "event": {
    "type": "caller_credential.failed",
    "code": "CALLER_CREDENTIAL_EXPIRED",
    "integrationId": "yekar.salesforce"
  }
}

integrationId identifies the integration whose caller authority was refused. Treat code as the stable decision field. The event contains no credential value, caller-supplied field name, or agent or flow definition detail.

Code	When it fires	What your application should do
`CALLER_CREDENTIAL_EXPIRED`	Caller material was supplied but its one-hour custody window elapsed before use.	Obtain fresh material from the end user and supply it on the next conversation turn. Do not retry the prior turn without resupplying it.
`CALLER_CREDENTIAL_REQUIRED`	Effective policy requires caller authority, but usable caller material was not supplied for the execution.	Ask the end user to connect or authorize the named integration, then include its material on the next turn.
`NO_CREDENTIAL_AVAILABLE`	Caller material was absent, fallback was allowed, and the organization has no stored credential for the integration.	Either have an administrator connect the integration for the organization or obtain end-user material and supply it on the next turn.
`CALLER_GRANT_CORRUPT`	Encrypted caller material could not be read. This is a system fault; Yekar.AI does not fall back to stored authority.	Resupply the end-user material on a new turn. If the refusal repeats with fresh material, stop retrying and contact support with the session id and integration id.
`CALLER_MODE_NOT_CALLABLE`	A nested agent or flow requires caller authority, but the calling execution has no caller-authorized context it can pass.	Start the target through an entry request that supplies the required caller material. Do not retry the same unattended nested call.

Nested calls

When a nested agent or flow encounters one of these refusals, the parent session emits the caller-credential code itself. It does not replace it with the generic outer AUTOMATION_CALL_FAILED code and does not emit both. This keeps the stream actionable while avoiding two events for one refusal.

The code names the refusal at the layer where it occurred. A code on a parent stream can therefore describe either the parent tool invocation or a child agent or flow. The failure event has no separate origin flag. Use the failed tool-call audit beside the event to distinguish them: a nested agent or flow call includes its child runId or sessionId. integrationId identifies the integration that refused authority; it does not identify the execution layer.

The ordinary tool_call.finished event is unchanged and still reports tool progress. caller_credential.failed is an additional event. Consumers that do not handle it can continue to reconcile from the transcript when the turn completes.

Nested calls​

Nested calls