Common API errors

Read the error envelope

API errors return code, message, requestId and optional safe details. Keep requestId when investigating or contacting support. Never paste API keys, passwords, provider credentials or raw customer content into a support ticket. Retry only when the code and operation make retry safe.

Account access, verification and password recovery

If sign-in is blocked, first use the supported verification or password-reset flow shown by Studio. Vira intentionally uses non-enumerating recovery copy, so support should not confirm whether an arbitrary email address has an account. Request a fresh verification/reset message instead of reusing an expired link. Never send passwords, reset tokens, session cookies or access tokens to support. If the recovery flow repeatedly cannot deliver or complete, keep the time of the attempt and the visible public-safe error state, then use the monitored support channel when available.

VALIDATION_FAILED

Meaning: the request does not match the API contract. Likely causes include a missing required field, invalid UUID, enum value or field shape. Remediation: compare the request with the current API reference and correct the payload. Retry only after changing the invalid input. Escalate with requestId if the documented contract and server validation disagree.

UNAUTHORIZED

Meaning: a valid scoped Vira API credential was not accepted for this operation. Check that the key belongs to the intended project, application and environment and includes the required capability. Do not send the secret to support. Retry after correcting or rotating the credential. Escalate with requestId and non-secret credential metadata if a known-active scoped key is rejected.

IDEMPOTENCY_KEY_REQUIRED / INVALID_IDEMPOTENCY_KEY

Meaning: a mutation is missing an Idempotency-Key or the key is invalid. Use one stable key for the same logical mutation across retries and keep it at 255 characters or fewer. Do not generate a fresh key for each retry of the same operation. Retry after fixing the header; escalate only if a valid stable key is still rejected.

RATE_LIMIT_EXCEEDED

Meaning: the project request rate limit was reached. Reduce request rate and use bounded exponential backoff with jitter where the calling operation is retry-safe. Preserve the same idempotency key for mutation retries. Escalate with requestId and approximate request volume if the limit appears inconsistent with the plan or configured policy.

PLAN_QUOTA_EXCEEDED

Meaning: the project usage quota is exhausted. Do not loop retries because quota exhaustion is not a transient transport failure. Review current usage and plan limits, then retry only after quota becomes available or the plan changes. Billing/support can investigate with requestId; never provide card details in a support message.

RESOURCE_NOT_FOUND

Meaning: the resource was not found inside the authorized scope. Confirm project, application, environment and resource identifiers. Vira intentionally avoids revealing cross-tenant resource existence. Retry after correcting scoped identifiers. Escalate with requestId and safe resource IDs only if the resource is visible in the same authorized project.

BEHAVIOR_POINT_NOT_REGISTERED

Meaning: the requested Behavior Point is not registered for the application. Register or select the intended Behavior Point for that exact application/environment before resolving. Retry after registration is authoritative. Escalate with requestId, application ID, environment and Behavior Point name if Studio shows it as registered but runtime still returns this code.

BEHAVIOR_POINT_PROFILE_UNBOUND / BEHAVIOR_POINT_PROFILE_AUTHORITY_MISMATCH

Meaning: runtime cannot establish an explicit governed profile authority for the Behavior Point. Inspect the exact application/environment binding and active authority chain; do not work around the failure with a wildcard or client-side revision. Retry after the binding is corrected and authoritative. Escalate with requestId and non-secret binding/profile identifiers if the mismatch persists.

BEHAVIOR_POINT_PROJECT_WILDCARD_FORBIDDEN / BEHAVIOR_POINT_RUNTIME_ROUTE_AMBIGUOUS

Meaning: the runtime route is too broad or ambiguous to serve authority safely. Replace project-global or conflicting routes with one explicit application/environment route and deterministic binding chain. Do not force a latest-wins fallback. Retry after route ambiguity is removed. Escalate with requestId and the affected Behavior Point if Studio cannot identify the conflicting route.

Lifecycle conflict (409)

Codes such as TARGET_REVISION_STALE, EVALUATION_GATE_FAILED, CANDIDATE_STATE_TERMINAL, API_KEY_NOT_ACTIVE and LAST_PROJECT_OWNER_REQUIRED mean the requested transition conflicts with current authoritative state. Refresh the current candidate/evaluation/deployment/account state and take the allowed next action instead of forcing the mutation. Retry only after state changes. Escalate with requestId and safe revision/deployment identifiers when the visible state does not explain the conflict.

REDIS_NOT_READY

Meaning: rate-limit authority is unavailable. Vira fails closed instead of silently bypassing the control. Treat this as a transient service dependency failure, retry with bounded backoff, and check service status if available. Escalate with requestId if the condition persists.

SERVER_MISCONFIGURED

Meaning: a required server-side security or signing configuration is missing. Client retries will not repair the configuration. Operators should restore the required production configuration before serving the affected flow. Escalate immediately with requestId; do not send secrets or environment values in the ticket.

INTERNAL_ERROR / REQUEST_FAILED

Meaning: the request could not be completed without exposing internal implementation details. Preserve requestId. For a safe idempotent read, a bounded retry may be appropriate; for mutations, preserve the same idempotency key. If the error repeats, escalate with requestId, timestamp, endpoint/operation and environment, excluding secrets and raw customer content.