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 in the request body, or a prompt/input mismatch.
401	UNAUTHORIZED	POST /auth/token was called without a signed-in browser session bound to an organization.
400	CALLER_CREDENTIALS_UNEXPECTED	Caller material was supplied for an integration that the target does not run at caller identity.
400	PASSWORD_BREACHED	The new password has appeared in a known data breach. Choose a different one. Sent where a password is set: accepting an invitation, resetting and changing it.
403	SSO_REQUIRED	The organization requires its own single sign-on, so a password or Google sign-in cannot enter it. details.ssoLoginUrl is where to sign in instead.
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.
422	VALIDATION	A publish was refused because the procedure verifier found problems; details.findings lists them.
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.
409	STALE_BINDINGS	Someone else changed an automation's integration bindings after you read them. Nothing was saved: read the automation again and reapply your change. Sent only when the request includes the revision it was read at.
409	STALE_TRIGGER_SELECTION	Someone else changed which triggers start an automation after you read them. Nothing was saved: read the selection again and reapply your change. Sent only when the request includes the revision it was read at.
429	RATE_LIMITED	The route's request window was exceeded. Retry-After names the seconds until it reopens. See Rate limits.
429	SIGN_IN_LOCKED	Ten failed password attempts in fifteen minutes locked the submitted sign-in address, or the signed-in account's current-password check. Retry-After and details.retryAfterSeconds name the wait; the right password is refused until then.
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.
503	ORG_RUN_RATE_BUDGET_UNAVAILABLE	The organization's run-initiation budget could not be checked, so the run was not started; Retry-After: 5.
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.
Runtime	CALLER_CREDENTIAL_REFRESH_FAILED	The provider refused to renew the caller-supplied token (for example a revoked refresh token); stored authority is never used instead. Fire again with fresh credentials.
Request	CALLER_REFRESH_CLIENT_REQUIRED	refresh was sent without clientId and your organization has no sign-in app for that integration.
Request	CALLER_REFRESH_TOKEN_URL_REQUIRED	refresh was sent without tokenUrl for an integration that has no token address of its own.
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.

Unknown fields are refused

Every request body is validated strictly: a field the endpoint does not accept is refused with 400 VALIDATION rather than ignored, so a misspelled field never succeeds while silently doing nothing. details names the field - at the top level of the body under formErrors, and inside a nested object under fieldErrors, keyed by that object's field:

{
  "error": {
    "code": "VALIDATION",
    "message": "Invalid request",
    "details": { "formErrors": ["Unrecognized key: \"callerCredential\""], "fieldErrors": {} }
  }
}

Send only the fields an endpoint documents.

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.