Errors

Non-success responses use one envelope:

{ "error": { "code": "NOT_FOUND", "message": "Trigger not found", "details": {} } }

details is present only when the error carries structured details.

Status	Code	Meaning
400	VALIDATION	Malformed JSON, a schema violation, an unknown field on a strict request body, or a prompt/input mismatch.
400	CALLER_CREDENTIALS_UNEXPECTED	Caller material was supplied for an integration that the target does not run at caller identity.
403	FORBIDDEN	The authenticated caller lacks the required permission or session visibility for a known resource.
403	SESSION_NOT_DRIVABLE	The session is visible, but this caller cannot send messages, upload files or control its turns. Evaluation replays also cannot be driven.
404	NOT_FOUND	Unknown or cross-organization id, invalid/revoked key, or a missing-or-unauthorized entry resource. Trigger ingress deliberately combines missing and unauthorized responses.
409	CONFLICT	The request conflicts with current state, such as a stale approval or a decision that was already made. Authorized agent follow-ups can queue during an active turn.
409	IDEMPOTENCY_KEY_REUSED	A fire idempotency key was reused with a different request.
409	IDEMPOTENCY_IN_PROGRESS	The first request using this fire idempotency key is still running.
409	IDEMPOTENCY_OUTCOME_UNKNOWN	The original fire may have taken effect, but its outcome cannot be replayed safely.
429	RATE_LIMITED	The route's current request window was exceeded.
429	AUTOMATION_AT_CAPACITY	The agent or flow's published concurrency limit has been reached.
429	ORG_RUN_RATE_LIMITED	The organization started more runs in one minute than its plan allows; Retry-After names the wait.
500	INTERNAL	Unexpected server failure.

For a visible evaluation replay, sending a new message returns 400 VALIDATION with the same read-only explanation shown in the session. Session visibility is checked before that explanation is returned.

Execution can also record errors after the HTTP request has already returned 202:

Phase	Code	Meaning
Runtime	CALLER_CREDENTIAL_REQUIRED	Effective policy required caller material and none was available.
Runtime	NO_CREDENTIAL_AVAILABLE	Stored fallback was allowed, but no organization credential was connected.
Runtime	CALLER_CREDENTIAL_EXPIRED	Supplied caller material expired before the step ran; it is not replaced by stored authority.
Trigger subscriber	CALLER_CREDENTIALS_REQUIRED	This subscriber requires caller material that the fire did not supply; other subscribers continue.
Runtime	CALLER_MODE_NOT_CALLABLE	An unattended nested execution tried to start an agent or flow that requires a caller.
Runtime	LLM_BUDGET_EXHAUSTED	The organization's or domain's monthly token cap stopped a model turn.
Runtime	LLM_BUDGET_UNAVAILABLE	Enforcement is fail-closed and budget consumption could not be checked.
Runtime	MANAGED_CAP_EXCEEDED	Managed spend passed the organization's monthly cost cap.
Runtime	MANAGED_BALANCE_EXHAUSTED	The prepaid managed balance cannot cover the next model call.
Runtime	AUTOMATION_CALL_TOO_DEEP	A nested call exceeded the organization's call-depth limit.
Runtime	AUTOMATION_CALL_TOO_MANY_CHILDREN	One execution started more direct children than the organization allows.
Runtime	AUTOMATION_CALL_TREE_TOO_LARGE	A call tree exceeded the organization's descendant limit.
Runtime	AUTOMATION_CALL_CYCLE	An agent or flow tried to call one already on its call stack.

Inspect the session, run read, stream, or trigger Run history for the outcome.

LLM_BUDGET_EXHAUSTED means an administrator must raise or clear the cap that bound, or wait for the next UTC calendar month. LLM_BUDGET_UNAVAILABLE means consumption could not be read while enforcement was fail-closed; retry after the budget service recovers.

Recover from fire idempotency conflicts

IDEMPOTENCY_KEY_REUSED

The same key was sent with a different target or request body. This is a client key-generation bug. Do not retry: generate keys so one key identifies exactly one logical fire request.

IDEMPOTENCY_IN_PROGRESS

The first request is still processing. Read Retry-After and retry the identical request with the same key after that interval. The current response sets Retry-After: 2, so this retry is safe after 2 seconds.

IDEMPOTENCY_OUTCOME_UNKNOWN

Do not blindly retry this response. The original request may or may not have taken effect, and the platform cannot prove which. Retrying without checking defeats the idempotency guarantee and may duplicate the effect.

First check whether the work happened: inspect the trigger's Run history. Only decide what to do next after reconciling that evidence.

Retry a capacity refusal

Guarded execution-creation routes return 429 AUTOMATION_AT_CAPACITY with Retry-After: 5 when the agent or flow has no available slot. No new execution is created by the refused request, so retrying after 5 seconds is safe. This is separate from 429 RATE_LIMITED, which protects request volume rather than execution capacity.

Accepted does not mean succeeded

A 202 means the work was accepted. Agent turns and Flow runs execute asynchronously. Trigger fan-out can accept the firing while recording per-subscriber failures; its response lists only sessions that started. Reconcile against the returned resource instead of treating 202 as a completed outcome.

The normal way to learn an outcome is a webhook; the session stream is how you reconcile when one did not arrive.

The internal @yekarai/sdk throws YekarApiError for non-2xx responses. Its public error fields are code, message, status, and optional details; the package is not published for third-party use yet.