Error codes

{ "error": { "code": "AIH-AUTH-0001",
             "message": "invalid login or password",
             "message_key": "err.auth.invalid_credentials",
             "details": { } } }

Every AiHummer API error carries a **stable machine code** in the form `AIH-<DOMAIN>-<NNNN>`. The wire shape is: ```json { "error": { "code": "AIH-AUTH-0001", "message": "invalid login or password", "message_key": "err.auth.invalid_credentials", "details": { } } } ``` `code` is stable (never reused or renumbered); `message` is a human English string; `message_key` is the i18n key clients use to localize; `details` is optional structured context. Codes are the single source of truth in `internal/apierr` and this page mirrors that registry. > Billing / plan-entitlement errors (the 402 "upgrade required" surface) are **not** listed here — see [Licensing & billing](/en/v1.0/commercial/licensing). ## COMMON Cross-cutting errors shared by every service (request shape, method, auth, internal failures). A domain-specific code is preferred when one fits. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-COMMON-0001` | 405 | Method not allowed | `err.common.method_not_allowed` | The HTTP method is not allowed for this route. | | `AIH-COMMON-0002` | 400 | Invalid request body | `err.common.invalid_body` | Malformed, incomplete or invalid request input. | | `AIH-COMMON-0003` | 400 | A required field is missing | `err.common.missing_field` | Malformed, incomplete or invalid request input. | | `AIH-COMMON-0004` | 500 | Internal error | `err.common.internal` | An unexpected internal failure. | | `AIH-COMMON-0005` | 404 | Not found | `err.common.not_found` | The referenced object does not exist or is out of scope. | | `AIH-COMMON-0006` | 403 | Forbidden | `err.common.forbidden` | The resource belongs to another tenant/owner/session. | | `AIH-COMMON-0007` | 501 | Feature not enabled | `err.common.not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-COMMON-0008` | 401 | Unauthorized | `err.common.unauthorized` | Missing or invalid credentials. | | `AIH-COMMON-0009` | 400 | Validation failed | `err.common.validation` | Malformed, incomplete or invalid request input. | | `AIH-COMMON-0010` | 409 | Conflict | `err.common.conflict` | Conflicts with current state. | | `AIH-COMMON-0011` | 429 | Rate limit exceeded | `err.common.rate_limited` | Too many requests / over the configured budget. | | `AIH-COMMON-0012` | 502 | Upstream error | `err.common.upstream` | An upstream/provider call failed. | ## AUTH Admin local-auth: login, sessions, password change, user management, 2FA. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-AUTH-0001` | 401 | Invalid login or password | `err.auth.invalid_credentials` | Missing or invalid credentials. | | `AIH-AUTH-0002` | 429 | Too many attempts, try again later | `err.auth.too_many_attempts` | Too many requests / over the configured budget. | | `AIH-AUTH-0003` | 401 | Not authenticated | `err.auth.not_authenticated` | Missing or invalid credentials. | | `AIH-AUTH-0004` | 501 | Local auth not enabled | `err.auth.local_disabled` | The feature/integration is turned off or unconfigured. | | `AIH-AUTH-0005` | 403 | Current password is wrong | `err.auth.wrong_current_password` | The resource belongs to another tenant/owner/session. | | `AIH-AUTH-0006` | 409 | You cannot delete your own account | `err.auth.cannot_delete_self` | Conflicts with current state. | | `AIH-AUTH-0007` | 500 | Could not create session | `err.auth.session_failed` | An unexpected internal failure. | | `AIH-AUTH-0008` | 501 | Two-factor auth not enabled | `err.auth.twofa_disabled` | The feature/integration is turned off or unconfigured. | | `AIH-AUTH-0009` | 401 | Challenge expired — sign in again | `err.auth.twofa_challenge_expired` | Missing or invalid credentials. | | `AIH-AUTH-0010` | 401 | Invalid code | `err.auth.twofa_invalid_code` | Missing or invalid credentials. | | `AIH-AUTH-0011` | 401 | Invalid recovery code | `err.auth.twofa_invalid_recovery` | Missing or invalid credentials. | | `AIH-AUTH-0012` | 401 | Second-factor verification failed | `err.auth.twofa_verify_failed` | Missing or invalid credentials. | | `AIH-AUTH-0013` | 400 | No matching second factor enrolled | `err.auth.twofa_not_enrolled` | Malformed, incomplete or invalid request input. | | `AIH-AUTH-0014` | 400 | Invalid or expired reset token | `err.auth.reset_token_invalid` | Malformed, incomplete or invalid request input. | ## AGENT AI-employee (agent) CRUD, versions, clone, and the per-agent system-prompt profile. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-AGENT-0001` | 501 | Agents not enabled | `err.agent.not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-AGENT-0002` | 404 | Agent not found | `err.agent.not_found` | The referenced object does not exist or is out of scope. | | `AIH-AGENT-0003` | 403 | Not your agent | `err.agent.forbidden` | The resource belongs to another tenant/owner/session. | | `AIH-AGENT-0004` | 501 | Agent profiles not enabled | `err.agent.profile_not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-AGENT-0005` | 404 | Shared section not found | `err.agent.section_not_found` | The referenced object does not exist or is out of scope. | | `AIH-AGENT-0006` | 403 | Not your shared section | `err.agent.section_forbidden` | The resource belongs to another tenant/owner/session. | | `AIH-AGENT-0007` | 400 | Unknown section kind | `err.agent.unknown_section_kind` | Malformed, incomplete or invalid request input. | | `AIH-AGENT-0008` | 403 | Tool not permitted for this agent | `err.agent.tool_not_permitted` | The resource belongs to another tenant/owner/session. | | `AIH-AGENT-0009` | 403 | Subagent depth limit reached | `err.agent.subagent_depth_exceeded` | The resource belongs to another tenant/owner/session. | | `AIH-AGENT-0010` | 403 | Handoff not available here | `err.agent.handoff_unavailable` | The resource belongs to another tenant/owner/session. | | `AIH-AGENT-0011` | 500 | Tool call failed | `err.agent.tool_failed` | An unexpected internal failure. | | `AIH-AGENT-0012` | 400 | Handoff requires 'agent' and 'task' | `err.agent.handoff_invalid_args` | Malformed, incomplete or invalid request input. | | `AIH-AGENT-0013` | 404 | No agent with that name | `err.agent.handoff_target_not_found` | The referenced object does not exist or is out of scope. | | `AIH-AGENT-0014` | 400 | No tasks provided | `err.agent.subagent_no_tasks` | Malformed, incomplete or invalid request input. | ## APIKEY API keys for programmatic gateway access: the key subsystem is not configured. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-APIKEY-0001` | 501 | API keys not configured | `err.apikey.not_configured` | The feature/integration is turned off or unconfigured. | ## APPROVAL Human-in-the-loop approval queue: the approval feature is off. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-APPROVAL-0001` | 501 | Approvals not enabled | `err.approval.not_enabled` | The feature/integration is turned off or unconfigured. | ## ARTIFACT Conversation artifacts (documents + runnable code): code-exec off, missing artifact/version, wrong kind, or bad runner output. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-ARTIFACT-0001` | 501 | Code execution not enabled | `err.artifact.exec_disabled` | The feature/integration is turned off or unconfigured. | | `AIH-ARTIFACT-0002` | 404 | Artifact not found | `err.artifact.not_found` | The referenced object does not exist or is out of scope. | | `AIH-ARTIFACT-0003` | 404 | Artifact version not found | `err.artifact.version_not_found` | The referenced object does not exist or is out of scope. | | `AIH-ARTIFACT-0004` | 400 | Artifact is not code | `err.artifact.not_code` | Malformed, incomplete or invalid request input. | | `AIH-ARTIFACT-0005` | 500 | Bad runner output | `err.artifact.bad_runner_output` | An unexpected internal failure. | | `AIH-ARTIFACT-0006` | 400 | Kind must be document or code | `err.artifact.invalid_kind` | Malformed, incomplete or invalid request input. | ## BACKUP Database backup from the admin surface. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-BACKUP-0001` | 501 | Database URL not configured for backup | `err.backup.not_configured` | The feature/integration is turned off or unconfigured. | | `AIH-BACKUP-0002` | 500 | Backup failed | `err.backup.failed` | An unexpected internal failure. | ## BATCH Batch request processing. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-BATCH-0001` | 501 | Batches not enabled | `err.batch.not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-BATCH-0002` | 404 | Batch not found | `err.batch.not_found` | The referenced object does not exist or is out of scope. | ## BUDGET Usage metering and model-spend budgets. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-BUDGET-0001` | 501 | Usage metering not enabled | `err.budget.usage_not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-BUDGET-0002` | 501 | Budgets not enabled | `err.budget.not_enabled` | The feature/integration is turned off or unconfigured. | ## BYOK Bring-your-own-key: tenant-supplied model-provider keys. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-BYOK-0001` | 501 | BYOK not configured | `err.byok.not_configured` | The feature/integration is turned off or unconfigured. | ## CHANGE Change records and the change-approval workflow. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-CHANGE-0001` | 404 | Change not found | `err.change.not_found` | The referenced object does not exist or is out of scope. | | `AIH-CHANGE-0002` | 403 | Self-approval not allowed: a different approver is required | `err.change.self_approval_forbidden` | The resource belongs to another tenant/owner/session. | ## CHAT OpenAI-compatible chat-completions endpoint. The wire shape stays OpenAI-compatible while adding a stable code. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-CHAT-0001` | 501 | OpenAI-compatible endpoint disabled | `err.chat.disabled` | The feature/integration is turned off or unconfigured. | | `AIH-CHAT-0002` | 401 | Invalid API key | `err.chat.invalid_key` | Missing or invalid credentials. | | `AIH-CHAT-0003` | 400 | Invalid chat request | `err.chat.invalid_request` | Malformed, incomplete or invalid request input. | | `AIH-CHAT-0004` | 429 | Rate or budget limit exceeded | `err.chat.rate_limited` | Too many requests / over the configured budget. | | `AIH-CHAT-0005` | 502 | Chat turn failed | `err.chat.turn_failed` | An upstream/provider call failed. | | `AIH-CHAT-0006` | 500 | Chat completion failed | `err.chat.internal` | An unexpected internal failure. | ## CONNECTION Integration OAuth connections: connect tickets, authorization steps and token exchange. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-CONNECTION-0001` | 400 | Invalid or expired connect ticket | `err.connection.ticket_invalid` | Malformed, incomplete or invalid request input. | | `AIH-CONNECTION-0002` | 400 | Plugin does not declare an OAuth flow | `err.connection.no_oauth_flow` | Malformed, incomplete or invalid request input. | | `AIH-CONNECTION-0003` | 400 | OAuth client not configured for this plugin | `err.connection.oauth_client_not_configured` | Malformed, incomplete or invalid request input. | | `AIH-CONNECTION-0004` | 400 | Authorization denied | `err.connection.auth_denied` | Malformed, incomplete or invalid request input. | | `AIH-CONNECTION-0005` | 400 | Missing code or state | `err.connection.missing_code_or_state` | Malformed, incomplete or invalid request input. | | `AIH-CONNECTION-0006` | 400 | Invalid or expired state | `err.connection.state_invalid` | Malformed, incomplete or invalid request input. | | `AIH-CONNECTION-0007` | 400 | Plugin OAuth config unavailable | `err.connection.oauth_config_unavailable` | Malformed, incomplete or invalid request input. | | `AIH-CONNECTION-0008` | 502 | Token exchange failed | `err.connection.token_exchange_failed` | An upstream/provider call failed. | | `AIH-CONNECTION-0009` | 500 | Could not store the token | `err.connection.store_token_failed` | An unexpected internal failure. | ## CREDENTIAL Per-user credential vault operations. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-CREDENTIAL-0001` | 501 | Credential vault not enabled | `err.credential.vault_not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-CREDENTIAL-0002` | 400 | Credential operation failed | `err.credential.vault_error` | Malformed, incomplete or invalid request input. | ## DEVICE The device bridge to the on-device companion app. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-DEVICE-0001` | 503 | Device service unavailable | `err.device.service_unavailable` | A dependent service is temporarily unavailable. | ## EVENTS The server event stream (SSE) for the admin UI and clients. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-EVENTS-0001` | 500 | Streaming unsupported | `err.events.streaming_unsupported` | An unexpected internal failure. | ## FACT Long-term memory facts about users. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-FACT-0001` | 404 | Fact not found | `err.fact.not_found` | The referenced object does not exist or is out of scope. | | `AIH-FACT-0002` | 403 | Not a user fact | `err.fact.not_user_fact` | The resource belongs to another tenant/owner/session. | ## GRAPH Agent graphs: declarative multi-agent orchestration. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-GRAPH-0001` | 501 | Agent graphs not enabled | `err.graph.not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-GRAPH-0002` | 404 | Graph not found | `err.graph.not_found` | The referenced object does not exist or is out of scope. | | `AIH-GRAPH-0003` | 403 | Not your graph | `err.graph.forbidden` | The resource belongs to another tenant/owner/session. | | `AIH-GRAPH-0004` | 501 | Graph execution not available in this deployment | `err.graph.exec_unavailable` | The feature/integration is turned off or unconfigured. | ## GUARDRAIL Content/behavior guardrail rules for agents. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-GUARDRAIL-0001` | 501 | Guardrails not configured | `err.guardrail.not_configured` | The feature/integration is turned off or unconfigured. | ## INBOUND Generic inbound webhook/ingest endpoints: channel→gateway message ingestion. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-INBOUND-0001` | 401 | Unauthorized | `err.inbound.unauthorized` | Missing or invalid credentials. | | `AIH-INBOUND-0002` | 400 | Invalid inbound payload | `err.inbound.invalid_payload` | Malformed, incomplete or invalid request input. | | `AIH-INBOUND-0003` | 500 | Inbound dispatch failed | `err.inbound.dispatch_failed` | An unexpected internal failure. | ## IPALLOW Admin-access IP allowlists. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-IPALLOW-0001` | 501 | IP allowlist not configured | `err.ipallow.not_configured` | The feature/integration is turned off or unconfigured. | ## KB Knowledge-base connectors: RAG feature off, stored connector config corrupt, or a bad uploaded archive. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-KB-0001` | 501 | Knowledge base not enabled | `err.kb.not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-KB-0002` | 500 | Stored config corrupt | `err.kb.config_corrupt` | An unexpected internal failure. | | `AIH-KB-0003` | 400 | Invalid knowledge archive | `err.kb.invalid_archive` | Malformed, incomplete or invalid request input. | ## LICENSE Instance licensing: applying the signed license. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-LICENSE-0001` | 501 | Licensing not enabled | `err.license.not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-LICENSE-0002` | 400 | Invalid license | `err.license.invalid` | Malformed, incomplete or invalid request input. | ## LLM In-product "Connect Codex (ChatGPT subscription)" device-authorization flow. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-LLM-0001` | 501 | Codex connect is unavailable: the secrets vault (AIHUMMER_MASTER_KEY) is not configured | `err.llm.codex_connect_disabled` | The feature/integration is turned off or unconfigured. | | `AIH-LLM-0002` | 502 | Could not start the Codex device-authorization flow | `err.llm.codex_connect_start_failed` | An upstream/provider call failed. | | `AIH-LLM-0003` | 500 | Could not clear the stored Codex connection | `err.llm.codex_disconnect_failed` | An unexpected internal failure. | ## MARKETPLACE Plugin marketplace install path: the slug is validated against the catalog before the async deploy. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-MARKETPLACE-0001` | 404 | Unknown module: not in the catalog | `err.marketplace.unknown_module` | The referenced object does not exist or is out of scope. | ## MEDIA Media blob fetch/stream endpoints: signed-token media access. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-MEDIA-0001` | 404 | Media not found | `err.media.not_found` | The referenced object does not exist or is out of scope. | | `AIH-MEDIA-0002` | 403 | Invalid or expired media token | `err.media.token_invalid` | The resource belongs to another tenant/owner/session. | | `AIH-MEDIA-0003` | 503 | Video understanding not configured | `err.media.video_not_configured` | A dependent service is temporarily unavailable. | ## MEMORY Long-term memory (Einstein) admin surface: the memory backend is not wired. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-MEMORY-0001` | 501 | Memory not configured | `err.memory.not_configured` | The feature/integration is turned off or unconfigured. | ## MODELACCESS Model-access rules (which models are available to which users/agents). | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-MODELACCESS-0001` | 501 | Model access not configured | `err.modelaccess.not_configured` | The feature/integration is turned off or unconfigured. | ## MODULE Plugin/module marketplace control surface: feature off, missing source/installation, ownership, or a malformed side-load upload. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-MODULE-0001` | 501 | Marketplace not enabled | `err.module.not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-MODULE-0002` | 404 | Source not found | `err.module.source_not_found` | The referenced object does not exist or is out of scope. | | `AIH-MODULE-0003` | 404 | Installation not found | `err.module.installation_not_found` | The referenced object does not exist or is out of scope. | | `AIH-MODULE-0004` | 403 | Not your installation | `err.module.installation_forbidden` | The resource belongs to another tenant/owner/session. | | `AIH-MODULE-0005` | 501 | Plugin upload disabled (no blob store) | `err.module.upload_disabled` | The feature/integration is turned off or unconfigured. | | `AIH-MODULE-0006` | 400 | Invalid plugin upload bundle | `err.module.invalid_bundle` | Malformed, incomplete or invalid request input. | ## PAIRING Device pairing (QR redeem), device-session validation, binding status. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-PAIRING-0001` | 400 | Pairing code required | `err.pairing.code_required` | Malformed, incomplete or invalid request input. | | `AIH-PAIRING-0002` | 401 | Invalid or expired pairing code | `err.pairing.invalid_code` | Missing or invalid credentials. | | `AIH-PAIRING-0003` | 401 | Bad inbound secret | `err.pairing.bad_inbound_secret` | Missing or invalid credentials. | | `AIH-PAIRING-0004` | 400 | A required field is missing | `err.pairing.field_required` | Malformed, incomplete or invalid request input. | | `AIH-PAIRING-0005` | 401 | Invalid or expired session | `err.pairing.session_invalid` | Missing or invalid credentials. | | `AIH-PAIRING-0006` | 400 | Token required | `err.pairing.token_required` | Malformed, incomplete or invalid request input. | ## PLAYGROUND The prompt/model playground. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-PLAYGROUND-0001` | 501 | Playground not enabled | `err.playground.not_enabled` | The feature/integration is turned off or unconfigured. | ## PROMPT The prompt/template library. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-PROMPT-0001` | 501 | Prompt library not configured | `err.prompt.not_configured` | The feature/integration is turned off or unconfigured. | | `AIH-PROMPT-0002` | 404 | Template not found | `err.prompt.template_not_found` | The referenced object does not exist or is out of scope. | ## PUSH Mobile push notifications via the fleet relay (the instance holds no vendor credentials). | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-PUSH-0001` | 503 | Push relay unavailable (no fleet bus / instance not registered) | `err.push.relay_unavailable` | A dependent service is temporarily unavailable. | | `AIH-PUSH-0002` | 502 | Push relay delivery failed | `err.push.relay_failed` | An upstream/provider call failed. | ## REGEN Response regeneration (regenerate). | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-REGEN-0001` | 501 | Regenerate not enabled | `err.regen.not_enabled` | The feature/integration is turned off or unconfigured. | ## SAML SAML single sign-on. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-SAML-0001` | 501 | SAML not available | `err.saml.not_available` | The feature/integration is turned off or unconfigured. | | `AIH-SAML-0002` | 400 | Assertion missing subject | `err.saml.assertion_invalid` | Malformed, incomplete or invalid request input. | ## SCHEDULE Scheduled/deferred message sends. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-SCHEDULE-0001` | 404 | Schedule not found | `err.schedule.not_found` | The referenced object does not exist or is out of scope. | ## SCIM SCIM user provisioning. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-SCIM-0001` | 501 | SCIM not enabled | `err.scim.not_enabled` | The feature/integration is turned off or unconfigured. | ## SECRET Per-tenant secret vault: the master key is absent, or the named secret does not exist. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-SECRET-0001` | 501 | Secrets not configured | `err.secret.not_configured` | The feature/integration is turned off or unconfigured. | | `AIH-SECRET-0002` | 404 | Secret not found | `err.secret.not_found` | The referenced object does not exist or is out of scope. | ## SENTIMENT Conversation analytics: sentiment and quality. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-SENTIMENT-0001` | 501 | Conversation analytics not enabled | `err.sentiment.not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-SENTIMENT-0002` | 404 | Not analyzed yet | `err.sentiment.not_analyzed` | The referenced object does not exist or is out of scope. | | `AIH-SENTIMENT-0003` | 422 | Could not analyze the conversation | `err.sentiment.unprocessable` | The request is valid but the content could not be processed. | ## SESSION Conversation/session + message admin surface: feature off, or the conversation/message is not the caller’s. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-SESSION-0001` | 501 | Conversations not enabled | `err.session.not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-SESSION-0002` | 403 | Not your conversation | `err.session.conversation_forbidden` | The resource belongs to another tenant/owner/session. | | `AIH-SESSION-0003` | 403 | Not your message | `err.session.message_forbidden` | The resource belongs to another tenant/owner/session. | ## SKILL Agent skills: library and ownership. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-SKILL-0001` | 501 | Skills not enabled | `err.skill.not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-SKILL-0002` | 404 | Skill not found | `err.skill.not_found` | The referenced object does not exist or is out of scope. | | `AIH-SKILL-0003` | 403 | Not your skill | `err.skill.forbidden` | The resource belongs to another tenant/owner/session. | ## SKILLOPT The skill optimizer: skill-improvement proposals. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-SKILLOPT-0001` | 501 | Skill optimizer not enabled | `err.skillopt.not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-SKILLOPT-0002` | 404 | Proposal not found | `err.skillopt.proposal_not_found` | The referenced object does not exist or is out of scope. | | `AIH-SKILLOPT-0003` | 403 | Not your proposal | `err.skillopt.proposal_forbidden` | The resource belongs to another tenant/owner/session. | ## SYSTEM Host system operations: logs and self-update. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-SYSTEM-0001` | 501 | Logs not available on this host | `err.system.logs_unavailable` | The feature/integration is turned off or unconfigured. | | `AIH-SYSTEM-0002` | 501 | Self-update not configured; run `sudo aihummer update` on the host | `err.system.update_not_configured` | The feature/integration is turned off or unconfigured. | ## USER Workspace user and role management. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-USER-0001` | 409 | You cannot change your own roles | `err.user.cannot_change_own_roles` | Conflicts with current state. | | `AIH-USER-0002` | 409 | Cannot remove the last owner | `err.user.cannot_remove_last_owner` | Conflicts with current state. | ## VOICE Voice turn endpoint (/v1/voice/turn): the SIP-bridge → gateway audio-turn surface. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-VOICE-0001` | 502 | Could not resolve conversation | `err.voice.resolve_failed` | An upstream/provider call failed. | | `AIH-VOICE-0002` | 502 | Voice turn failed | `err.voice.turn_failed` | An upstream/provider call failed. | ## WEBCONN Embeddable web-chat widget connector: browser session + SSE chat. Streaming SSE error events are not part of this envelope. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-WEBCONN-0001` | 403 | Conversation does not belong to your session | `err.webconn.forbidden` | The resource belongs to another tenant/owner/session. | | `AIH-WEBCONN-0002` | 500 | Streaming unsupported | `err.webconn.streaming_unsupported` | An unexpected internal failure. | ## WEBHOOK Outbound webhooks for instance events. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-WEBHOOK-0001` | 501 | Webhooks not enabled | `err.webhook.not_enabled` | The feature/integration is turned off or unconfigured. | | `AIH-WEBHOOK-0002` | 404 | Webhook not found | `err.webhook.not_found` | The referenced object does not exist or is out of scope. | ## WORKSPACE Workspace ownership/scoping: the acting tenant acted on a workspace it does not own. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-WORKSPACE-0001` | 403 | Not your workspace | `err.workspace.forbidden` | The resource belongs to another tenant/owner/session. | ## ZAPIER The Zapier connector inbound trigger. | Code | HTTP | Meaning | i18n key | Typical cause | | --- | --- | --- | --- | --- | | `AIH-ZAPIER-0001` | 501 | Inbound trigger not configured | `err.zapier.not_configured` | The feature/integration is turned off or unconfigured. | | `AIH-ZAPIER-0002` | 401 | Invalid trigger signature or token | `err.zapier.invalid_signature` | Missing or invalid credentials. |