Every AiHummer API error carries a stable machine code in the form AIH-<DOMAIN>-<NNNN>. The wire shape is:
{ "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.
Billing / plan-entitlement errors (the 402 “upgrade required” surface) are not listed here — see Licensing & billing.
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. |
AIH-AUTH-0015 |
403 |
Set your own password first |
err.auth.password_change_required |
— |
AIH-AUTH-0016 |
400 |
The new password must differ from the current one |
err.auth.password_unchanged |
— |
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. |
AIH-AGENT-0015 |
403 |
Tool not available on this managed AiHummer Cloud instance |
err.agent.tool_cloud_restricted |
— |
AIH-AGENT-0016 |
409 |
This AI employee was changed elsewhere after you opened the card. Reopen the card and save again. |
err.agent.revision_conflict |
— |
AIH-AGENT-0017 |
400 |
No enabled model provider serves this model. Pick one from the list or enable its provider on the Models page. |
err.agent.model_not_served |
— |
AIH-AGENT-0018 |
400 |
The access rules name a person or an agent that does not exist in this workspace. |
err.agent.interaction_unknown_grant |
— |
AIH-AGENT-0019 |
400 |
The subagent restrictions name a tool this instance does not have. |
err.agent.interaction_unknown_tool |
— |
AIH-AGENT-0020 |
400 |
The chosen provider is disabled, deleted or does not serve this model. Pick another provider or «Any provider». |
err.agent.model_provider_invalid |
— |
AIH-AGENT-0021 |
400 |
An agent can have at most 8 spare models of its own. Remove one before adding another. |
err.agent.too_many_spares |
— |
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. |
AIH-APPROVAL-0002 |
409 |
The request has expired: nobody decided in time, so the call was already refused. The agent will ask again if it still needs this. |
err.approval.expired |
— |
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. |
AIH-CHAT-0007 |
503 |
No AI model provider is configured yet — add one in the Models section |
err.chat.no_llm_provider |
— |
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. |
AIH-FACT-0003 |
409 |
The fact’s status does not allow this decision: only a candidate can be approved, and only a candidate or an approved fact can be rejected. Refresh the list. |
err.fact.status_conflict |
— |
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. |
AIH-INBOUND-0004 |
503 |
The server is busy — the message is saved but not processed yet. Retry with the same message ID. |
err.inbound.server_busy |
— |
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. |
AIH-KB-0004 |
413 |
Attachment exceeds the maximum allowed size |
err.session.attachment_too_large |
— |
AIH-KB-0005 |
413 |
Attachment exceeds the maximum allowed size |
err.session.attachment_too_large |
— |
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. |
AIH-LICENSE-0003 |
409 |
This licence requires a signed installation grant. Request a current licence bundle from the vendor. |
err.license.grant_required |
— |
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. |
AIH-LLM-0004 |
501 |
No model providers are configured |
err.llm.providers_not_configured |
— |
AIH-LLM-0005 |
404 |
Model provider not found |
err.llm.provider_not_found |
— |
AIH-LLM-0006 |
400 |
Invalid model provider configuration |
err.llm.provider_invalid |
— |
AIH-LLM-0007 |
502 |
Provider test failed |
err.llm.provider_test_failed |
— |
AIH-LLM-0008 |
501 |
Provider test is unavailable |
err.llm.provider_test_unavailable |
— |
AIH-LLM-0009 |
502 |
OpenAI is not available from the server’s region — an outbound proxy in an allowed region is required. Contact support. |
err.llm.region_blocked |
— |
AIH-LLM-0010 |
501 |
Claude subscription connect is unavailable on this instance |
err.llm.claude_connect_disabled |
— |
AIH-LLM-0011 |
502 |
Could not connect the Claude subscription |
err.llm.claude_connect_failed |
— |
AIH-LLM-0012 |
500 |
Could not clear the stored Claude subscription connection |
err.llm.claude_disconnect_failed |
— |
AIH-LLM-0013 |
400 |
This account does not serve this model: pick a model from the account’s list. |
err.llm.provider_model_not_in_catalog |
— |
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 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. |
AIH-MEMORY-0002 |
404 |
This contradiction was not found — refresh the list. |
err.memory.contradiction_not_found |
— |
AIH-MEMORY-0003 |
409 |
This contradiction has already been decided or reopened — refresh the list. |
err.memory.contradiction_conflict |
— |
AIH-MEMORY-0004 |
409 |
A memory check is already running. Wait for it to finish. |
err.memory.quality_busy |
— |
AIH-MEMORY-0005 |
404 |
This fix no longer exists — refresh the page. |
err.memory.quality_fix_not_found |
— |
AIH-MEMORY-0006 |
409 |
This fix cannot be undone: it was already undone, or the facts were changed after it. |
err.memory.quality_fix_conflict |
— |
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. |
AIH-MODULE-0007 |
403 |
The official catalog source cannot be disabled or removed |
err.module.source_protected |
— |
AIH-MODULE-0008 |
403 |
This module is a built-in part of the product and cannot be removed or stopped |
err.module.builtin_protected |
— |
AIH-MODULE-0009 |
409 |
This plugin requests permissions you need to review and approve before installing |
err.module.consent_required |
— |
AIH-MODULE-0010 |
400 |
The plugin requests access it did not declare in its capability manifest |
err.module.capability_violation |
— |
AIH-MODULE-0011 |
410 |
This module is retired: its function is built into the product core, so it can no longer be installed |
err.module.retired |
— |
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. |
AIH-PAIRING-0007 |
401 |
The pairing code has expired — generate a fresh QR code and scan it again. |
err.pairing.code_expired |
— |
AIH-PAIRING-0008 |
401 |
This pairing code was already used — generate a fresh QR code. |
err.pairing.code_used |
— |
AIH-PAIRING-0009 |
403 |
This device binding is deactivated — re-enable it in the AiHummer admin UI and try again. |
err.pairing.binding_inactive |
— |
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 vendor push relay (the instance holds no vendor credentials).
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-PUSH-0001 |
503 |
Push relay unavailable (vendor push service unavailable / 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. |
AIH-SCHEDULE-0002 |
409 |
The schedule can’t be turned on yet: some conditions are not met |
err.schedule.blocked |
— |
AIH-SCHEDULE-0003 |
409 |
A block is removed with the «Remove block» action, not by editing the payload |
err.schedule.unblock_required |
— |
AIH-SCHEDULE-0004 |
400 |
Choose a recipient: the schedule has a delivery channel but no chat to deliver to |
err.schedule.recipient_required |
— |
AIH-SCHEDULE-0006 |
409 |
Commands on the server in schedules are turned off. The owner or an administrator can turn them on in System & settings → Schedules. |
err.schedule.commands_off |
— |
AIH-SCHEDULE-0007 |
409 |
This exact command is not among the allowed commands. The owner or an administrator can add it in System & settings → Schedules. |
err.schedule.command_not_allowed |
— |
AIH-SCHEDULE-0008 |
400 |
This chat cannot receive scheduled messages: web chat and API conversations have no outbound delivery. Choose a messenger chat. |
err.schedule.recipient_undeliverable |
— |
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. |
AIH-SESSION-0004 |
413 |
Attachment exceeds the maximum allowed size |
err.session.attachment_too_large |
— |
AIH-SESSION-0005 |
404 |
Attachment not found |
err.session.attachment_not_found |
— |
AIH-SESSION-0006 |
502 |
The message did not reach the channel |
err.session.operator_reply_undelivered |
— |
AIH-SESSION-0007 |
409 |
This message is not an agent reply in an app chat |
err.session.not_app_reply |
— |
AIH-SESSION-0008 |
503 |
Delivery to the app is not available on this instance |
err.session.app_delivery_unavailable |
— |
AIH-SESSION-0009 |
503 |
The AiHummer App module is not running — start it on the Plugins page, then deliver again |
err.session.app_module_not_running |
— |
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. |
AIH-SYSTEM-0003 |
501 |
Sidecar install is not available on this host — run the signed installer with --sidecar <name>. |
err.system.sidecar_not_configured |
— |
AIH-SYSTEM-0004 |
501 |
This server cannot restart itself from the panel. The saved value will take effect the next time the server is restarted — ask whoever administers it, or restart it from your hosting provider’s control panel. |
err.system.restart_not_configured |
— |
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
Admin Sessions backend: 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. |
AIH-WEBCONN-0003 |
409 |
This AI employee’s app settings are damaged. The owner can fix them in the agent profile: «Context and behaviour» → «AiHummer app». |
err.webconn.app_policy_invalid |
— |
AIH-WEBCONN-0004 |
404 |
Not found |
err.common.not_found |
— |
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. |
AIH-WORKSPACE-0002 |
404 |
Workspace not found |
err.workspace.not_found |
— |
AIH-WORKSPACE-0003 |
409 |
Cannot delete the last workspace |
err.workspace.cannot_delete_last |
— |
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. |
ANALYSIS
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-ANALYSIS-0001 |
503 |
The current source reader is unavailable. A shared analysis or a business-record link does not grant access to source data. |
businessResults.sourceUnavailable |
— |
BINDING
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-BINDING-0001 |
400 |
The binding rule is invalid: pick a channel, a scope and exactly one target — an agent or «do not reply». |
err.binding.invalid_rule |
— |
AIH-BINDING-0002 |
409 |
A binding for this target already exists — remove or edit the existing one. |
err.binding.overlap |
— |
AIH-BINDING-0003 |
404 |
Binding not found. |
err.binding.not_found |
— |
AIH-BINDING-0004 |
400 |
A @handle is not the account id this channel sends — add the person by their numeric channel id. |
err.binding.handle_not_identity |
— |
AIH-BINDING-0005 |
409 |
This group or channel is already connected to another organization on this server — it cannot be bound to an agent here. |
err.binding.chat_taken |
— |
BROWSER
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-BROWSER-0001 |
503 |
The browser profile service is not running. It starts together with the browser. |
err.browserprofile.service_unavailable |
— |
AIH-BROWSER-0002 |
409 |
This agent already has a browser profile. Unlink the agent from it first. |
err.browserprofile.agent_taken |
— |
AIH-BROWSER-0003 |
409 |
The profile is busy right now: someone is signing in to it. Try again in a few minutes. |
err.browserprofile.busy |
— |
AIH-BROWSER-0004 |
409 |
The browser still has this profile open: an agent is finishing an action in it. Try again in a minute. |
err.browserprofile.in_use |
— |
CLAIM
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-CLAIM-0001 |
409 |
The identification window is closed — open it again. |
err.claim.window_closed |
— |
AIH-CLAIM-0002 |
404 |
This sender did not write while the window was open. |
err.claim.candidate_unknown |
— |
DATA
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-DATA-0001 |
503 |
The current source processing rules could not be verified. |
dataPolicy.errorUnavailable |
— |
AIH-DATA-0002 |
409 |
The selected processing route is not allowed for this source. Choose an already authorized compatible route or review the source policy. |
dataPolicy.errorIncompatible |
— |
AIH-DATA-0003 |
503 |
No verified compatible processing route is configured for this operation. Configure its processing location and retention profile. |
dataPolicy.errorUnconfigured |
— |
AIH-DATA-0004 |
409 |
The processing route changed during this operation. Review the current route before a fresh explicit request. |
dataPolicy.errorChanged |
— |
AIH-DATA-0005 |
409 |
Earlier content has no verified source classification. Its processing location has not been assumed. Use a fresh context or review the original source classification. |
dataPolicy.errorProvenanceUnknown |
— |
AIH-DATA-0006 |
409 |
The original media bytes could not be verified for this request. Reopen the existing attachment before trying a new request. |
dataPolicy.errorFingerprintUnavailable |
— |
AIH-DATA-0007 |
409 |
The processing configuration changed. Reload its current revision before saving. |
dataPolicy.errorConfigurationChanged |
— |
DELEGATION
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-DELEGATION-0001 |
403 |
This external connection is not currently assigned to this user and agent. |
enterpriseConnections.errorDenied |
— |
AIH-DELEGATION-0002 |
409 |
The external identity, connection or current authority changed. Reload the current connection. |
enterpriseConnections.errorChanged |
— |
AIH-DELEGATION-0003 |
503 |
The configured issuer, provider version or delegation profile is unavailable or incompatible. |
enterpriseConnections.errorUnavailable |
— |
AIH-DELEGATION-0004 |
409 |
An earlier external token issuance has no settled receipt. Review the provider’s actual issuance before a new attempt. |
enterpriseConnections.errorReconcile |
— |
AIH-DELEGATION-0005 |
409 |
The enterprise connection configuration changed. Reload its current revision before saving. |
enterpriseConnections.errorConfigurationChanged |
— |
DEMO
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-DEMO-0001 |
403 |
This action is disabled on the public demo stand |
err.demo.restricted |
— |
AIH-DEMO-0002 |
403 |
This is part of the demo stand itself and cannot be removed or stopped |
err.demo.protected |
— |
AIH-DEMO-0003 |
403 |
Email notifications are switched off on the public demo stand and cannot be switched on |
err.demo.email_disabled |
— |
IMPORT
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-IMPORT-0001 |
409 |
The part does not continue the upload; it resumes from where the server stopped |
err.import.upload_offset |
— |
AIH-IMPORT-0002 |
422 |
The uploaded file differs from the file on your computer. Upload it again |
err.import.upload_checksum |
— |
AIH-IMPORT-0003 |
413 |
The export is larger than the import allows |
err.import.too_large |
— |
AIH-IMPORT-0004 |
507 |
Not enough disk space on the server for the export and its unpacking |
err.import.no_space |
— |
AIH-IMPORT-0005 |
422 |
The archive contains paths outside itself and was not unpacked |
err.import.unsafe_archive |
— |
AIH-IMPORT-0006 |
422 |
No import source recognizes this export |
err.import.not_recognized |
— |
AIH-IMPORT-0007 |
409 |
The upload is not complete yet |
err.import.upload_incomplete |
— |
AIH-IMPORT-0008 |
424 |
The database backup before the import failed, so nothing was applied. Check that pg_dump is installed on the server |
err.import.backup_failed |
— |
NOTIFY
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-NOTIFY-0001 |
501 |
Notifications are not enabled |
err.notify.not_enabled |
— |
AIH-NOTIFY-0002 |
400 |
Invalid notification preference |
err.notify.invalid_pref |
— |
AIH-NOTIFY-0003 |
503 |
Telegram linking is unavailable |
err.notify.telegram_unavailable |
— |
AIH-NOTIFY-0004 |
502 |
Checking Telegram status failed — try again |
err.notify.telegram_transient |
— |
ONBOARDING
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-ONBOARDING-0001 |
503 |
No connection to the AiHummer servers. Check this server’s internet connection so the instance registration can finish. |
err.onboarding.awaiting_fleet |
— |
AIH-ONBOARDING-0002 |
400 |
The owner id must be a UUID |
err.onboarding.invalid_owner |
— |
PLAN
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-PLAN-0001 |
402 |
This AI employee is outside the current plan’s allowance — renew the subscription to bring it back. |
err.plan.agent_over_limit |
— |
ROLE
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-ROLE-0001 |
400 |
Invalid role definition |
err.role.invalid |
— |
AIH-ROLE-0002 |
409 |
A role with this name already exists |
err.role.exists |
— |
AIH-ROLE-0003 |
404 |
Role not found |
err.role.not_found |
— |
AIH-ROLE-0004 |
400 |
Built-in roles are read-only |
err.role.builtin_readonly |
— |
AIH-ROLE-0005 |
409 |
The role is still assigned to users — revoke it first |
err.role.in_use |
— |
SETTINGS
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-SETTINGS-0001 |
403 |
This setting is managed by AiHummer Cloud and cannot be changed |
err.settings.cloud_locked |
— |
AIH-SETTINGS-0002 |
400 |
Code execution was not set to «Only in a sandbox»: the OS sandbox (bubblewrap) does not start on this server and no container image is set. Install bubblewrap or choose «On this server». |
err.settings.code_exec_sandbox_unavailable |
— |
SUPPORT
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-SUPPORT-0001 |
503 |
No connection to the vendor — the fleet bus is offline. Try again later. |
err.support.unavailable |
— |
AIH-SUPPORT-0002 |
400 |
The support service rejected the request |
err.support.rejected |
— |
TURN
| Code |
HTTP |
Meaning |
i18n key |
Typical cause |
AIH-TURN-0001 |
502 |
The model provider rejected its credentials |
err.turn.provider_auth |
— |
AIH-TURN-0002 |
429 |
The request was limited by the provider or budget policy |
err.turn.rate_limited |
— |
AIH-TURN-0003 |
502 |
A required service is temporarily unavailable |
err.turn.upstream_unavailable |
— |
AIH-TURN-0004 |
502 |
A tool required by this turn failed |
err.turn.tool_failed |
— |
AIH-TURN-0005 |
502 |
The task did not fit into the step limit of one turn |
err.turn.step_limit |
— |
AIH-TURN-0006 |
502 |
The conversation no longer fits the model’s context window |
err.turn.context_overflow |
— |
AIH-TURN-0007 |
503 |
The scheduled turn was interrupted by a server restart |
err.turn.interrupted_restart |
— |
AIH-TURN-0008 |
503 |
The server is busy with other replies — the message was not processed. Send it again. |
err.turn.server_busy |
— |
AIH-TURN-0009 |
409 |
The task stage has stopped. Check the current task state. |
err.turn.task_stopped |
— |