Errors and exit codes

Exit codes

Code	Meaning	What to do
`0`	Success	—
`1`	Recoverable	Retry with backoff
`2`	Fatal	Surface it to the user; do not retry
`64`	Usage error	Fix the call shape

The exit code tells you whether to continue. The reason is always in the stdout envelope — see output protocol.

Typed error codes

Code	Retry?	What it means and what to do
`INVALID_ARG`	No	Your call is malformed. Read `error.details.expected` and `did_you_mean`, repair, run once.
`NOT_FOUND`	No	The named entity does not exist. `list` first, then call with a real name or id.
`RATE_LIMITED`	Yes	Back off and retry, up to three times.
`CLIENT_TIMEOUT`	Yes	The CLI's own clock fired, not a server failure. The job may still be running.
`NETWORK_ERROR`	Yes	Egress is blocked in this environment. Grant access, or use the MCP server.

`INVALID_ARG`

A usage error is a bug in the call, not a transient failure:

{
  "error": {
    "code": "INVALID_ARG",
    "details": {
      "expected": "hsCode (6-digit string)",
      "did_you_mean": "--hsCode"
    }
  }
}

Common causes: a flag that does not exist on that verb, a value in the wrong format, snake_case instead of camelCase, a --inputs file over 1000 rows, and list values broken by shell quoting.

`CLIENT_TIMEOUT`

The client-side timeout — 180s by default — fired before the server replied. error.details.timeoutMs shows the limit, and the envelope's nextActions carries the exact --stream re-run.

EXIMAGENT_TIMEOUT_MS=600000 eximagent enrich contacts --collectionId <id>

`NETWORK_ERROR`

Every command makes an HTTPS call on port 443. A connection or socket error is this environment blocking egress — not an outage.

Fixes, in order of preference:

Grant egress and keep the sandbox on. Under a coding agent, enable network access for the workspace rather than disabling isolation.
Use the hosted MCP server, which connects from the host and needs no sandbox change.
Set HTTPS_PROXY behind a corporate proxy.
Allow the host through firewall or antivirus.

Never disable the sandbox wholesale.

Authentication failures

An expired session presents as a command that used to work and now does not:

eximagent whoami
eximagent login

Empty results

An empty result set is not necessarily an error. On shipment queries check the coverage envelope first — status: unavailable means the lane is not visible, which is different from the trade not happening. See coverage and data sources.