Skip to Content
Browse documentation

EAPI Output and Error Handling

Handle EAPI YAML/JSON envelopes, process exit codes, symbolic errors, unknown disk usage and complete-inventory failures in local integrations.

All normal EAPI command results use the same envelope. Read it from stdout and check the process exit code. Help output is an exception: it is plain text. An integration that cannot start the binary or that times out might receive no structured output, so handle process errors before assuming JSON is available.

Response fields

FieldTypeMeaning
statusstringok on success, failed on failure.
commandstring or nullRecognized command, or null when no supported command was identified.
messagestringHuman-readable description; use error.code for branching.
dataobjectCommand payload; empty on handled command failures.
metaobjectCounts or other command metadata; empty where unused.
errorobject or nullNull on success; failure contains a symbolic code.

YAML is the default. --json emits one JSON object; --yaml explicitly selects YAML. The serializer normalizes values through JSON, preserving booleans, nulls and numbers; timestamps and other safe YAML scalars without a JSON-native representation become strings. Do not compare YAML text formatting to decide whether two results are equivalent.

Exit codes

Exit codeMeaning
0Successful command, or authorized help invocation.
1Command, record, serialization or unexpected internal failure.
2INVALID_ARGUMENTS or PERMISSION_DENIED.

An invalid command such as the removed login command is rejected by the parser as INVALID_ARGUMENTS. Missing required fields, unknown options and mixed --json/--yaml flags are also argument errors. For error-format selection the runner checks whether the exact --json token is present; otherwise its fallback error format is YAML. A mixed-format error can therefore be JSON even though the arguments are invalid.

Current symbolic errors

CodeMeaning
INVALID_ARGUMENTSInvalid CLI syntax, options or missing required arguments.
PERMISSION_DENIEDEffective UID is neither root nor the installed eenos UID.
INVALID_USERUsername fails the EAPI name pattern.
INVALID_DOMAINMissing or unsafe domain argument in the library.
ACCOUNT_NOT_FOUNDRequired hosting-user record is absent.
DOMAIN_NOT_FOUNDDomain owner or exact domain record cannot be found.
PACKAGE_NOT_FOUNDA package record disappears or cannot be found when read.
RESELLER_NOT_FOUNDRequired migration reseller-detail record is absent.
DOMAIN_INVENTORY_NOT_FOUNDRequired per-account main domain inventory is absent.
DATA_READ_FAILEDRecord cannot be read/decoded or contains invalid YAML.
INVALID_DATAA record has the wrong shape, a required domain inventory is invalid or a response cannot be serialized.
INVENTORY_READ_FAILEDAccount/reseller/package inventory directory cannot be read.
INVALID_COMMANDUnknown command passed directly to the library; ordinary CLI unknown commands are rejected earlier as INVALID_ARGUMENTS.
INTERNAL_ERRORUnexpected runner failure; message is Unable to complete command.

For example, a missing user record returns exit 1:

{
  "status": "failed",
  "command": "userinfo",
  "message": "Requested record was not found",
  "data": {},
  "meta": {},
  "error": {"code": "ACCOUNT_NOT_FOUND"}
}

Empty, unknown and incomplete data

A valid empty account, reseller or package directory returns success with an empty array and count 0. Failure to read a required record or inventory is not equivalent to that empty result. Discard failed results instead of importing a partial inventory into another system.

The listaccounts and migrationinfo disk_usage field uses recorded current-month MB values. Missing or unreadable usage data, absent per-user readings, invalid values and negative values become null. A genuine recorded zero remains 0. The read-only SQLite lookup does not create or repair a missing database. Do not turn unknown usage into zero for migration sizing.

migrationinfo requires a valid main domain inventory per account. Optional domain lists can be omitted and become empty arrays, but malformed categories or an absent main domain fail discovery. It does not fall back to an incomplete successful account list.

Consume results safely

Use a fixed command allowlist and argument arrays. Validate the expected command and envelope; check the exit code before consuming data. Apply a process deadline and choose a streaming or memory strategy appropriate to the full inventory size. The per-command Python/PHP snippets are standalone examples that read complete output into memory, not a background service or privilege configuration.

Keep raw configuration output and any cached inventories private to the authorized integration. EAPI is read-only; downstream imports, provisioning or migration actions remain separate operations.