Error reference

Cause: The Authorization header is missing, malformed, or contains a token that does not match the registered hash.

Fix: Ensure IICP_NODE_TOKEN is set correctly. The directory stores a bcrypt hash on first registration — if you changed the token you must re-register.

Cause: The JWT used for session-scoped requests has expired.

Fix: Re-authenticate: call POST /api/v1/register to obtain a fresh session JWT.

Cause: The node_id supplied does not exist in the directory.

Fix: Verify the node_id matches the value used at registration. Check that the node has not been deregistered.

Cause: The task intent URN is not in the node's declared capabilities list.

Fix: Update the adapter configuration to include the intent URN, or route the task to a node that advertises that capability.

Cause: The model name in the task payload is not in the node's model list (CIP-R2, spec §2).

Fix: Specify a model that the node advertises, or remove the model constraint and let the node use its default. Check GET /api/v1/discover to see which models each node supports.

Cause: All concurrency slots for the requested QoS class are occupied. Includes qos_class and retry_after_ms fields. Also sets Retry-After header. Error code: IICP-E019.

Fix: The proxy will node-switch immediately on this error — no retry to the same node. If you are calling the adapter directly, wait retry_after_ms milliseconds then try a different node.

Cause: This adapter is acting as a CIP worker and has reached its max_concurrent_remote limit: all concurrent remote-inference slots are occupied. The request is rejected immediately without queuing (spec §2.2: MUST NOT silently queue). Error code: IICP-E021.

Fix: The coordinator proxy will select a different CIP worker on this error. If you are calling the node directly as a CIP worker endpoint, retry against a different node. Operators: raise IICP_MAX_CONCURRENT (env var / --max-concurrent flag) to accept more simultaneous sub-tasks.

Cause: Zero CIP workers responded within the worker_timeout budget (worker_timeout = coordinator_timeout × 0.6 per spec §6). All selected workers either timed out or were unreachable before the deadline. Returned only when local fallback is disabled — otherwise the coordinator retries locally. Error code: IICP-E024.

Fix: 1) Check that CIP worker nodes are online and healthy (GET /api/v1/discover?cip_capable=1). 2) Increase the coordinator timeout in your client config to give workers more time. 3) Enable local fallback so timed-out CIP dispatch falls back to local execution instead of failing. 4) If workers are consistently slow, check inference backend load on the worker nodes.

Cause: The task did not complete within the deadline declared in the task payload.

Fix: Increase the deadline field in the task payload, or use a model with lower latency. Check GET /iicp/health on the adapter to see current queue depth.

Cause: The local inference backend (Ollama, vLLM, etc.) is not responding.

Fix: Verify the backend is running: curl http://localhost:11434/api/tags (Ollama) or curl http://localhost:8000/health (vLLM). The node will send heartbeats but fail all tasks until the backend is restored.

Cause: No eligible CIP worker nodes were reachable or accepted the task. The proxy attempted redundancy dispatch but no worker returned a successful result before the deadline.

Fix: Check that at least one CIP-enabled node with the required intent is online via GET /api/v1/discover?cip_capable=1. Retry the task or increase the timeout. Consensus voting (majority_of_3, majority_of_5) is planned for Phase 5E.

Cause: The task was rejected by the node's CIP policy gate: the intent type (e.g. file access, tool execution) is not allowed by this node's configuration.

Fix: Route the task to a node that permits the required capabilities. Check node capabilities in the discover response.

Cause: Too many registration attempts from this source IP within the rate-limit window (60 requests per 60 seconds per source IP). The response body carries a `retry_after_seconds` field (seconds until the window resets).

Fix: Wait retry_after_seconds before re-registering. If you are running many nodes behind the same NAT, stagger their start times or use different source IPs. For the SDK iicp-node serve, this is handled automatically — the node backs off and retries on start.

Cause: The HMAC-SHA256 signature on a credit award request does not match. Base canonical: task_id:tokens_used:cip_parent_task_id:cip_session_key:nonce:response_hash; CIP v0.6.11+ extended: append :querying_node_id when present. Returned as IICP-E027 with HTTP 422.

Fix: Verify that the node_hmac_key matches what the directory issued at registration (returned in the POST /register response). Ensure the nonce field is unique per request.

Cause: The request body failed schema validation — missing required fields, wrong types, or values outside allowed ranges.

Fix: Inspect the errors array in the response body for the specific field and constraint that failed. Consult the spec for the full field requirements.

Cause: Node registration failed due to invalid fields (e.g. duplicate node_id, invalid public_endpoint URL, or unsupported region).

Fix: Check the errors array in the response. Ensure public_endpoint is a valid URL reachable from outside your network, and that node_id is unique in the mesh.

Cause: The model name in the task payload is not registered on this adapter node. Error code: IICP-E029.

Fix: Check the adapter's supported model list (GET /iicp/health). Specify a model that this node advertises, or route to a different node. The proxy retries on a fresh node automatically.

Cause: The relay target peer_id is not in this adapter's peer list. The peer list refreshes every 30 seconds via gossip — a newly registered peer may not appear immediately. Error code: IICP-E030.

Fix: Wait up to 30 seconds for the gossip cycle to propagate the peer, then retry. If the peer_id is stale, re-discover via the directory.

Cause: The adapter attempted to forward the task to a peer but the peer was unreachable or returned an error. Error code: IICP-E031.

Fix: The proxy will node-switch on this error. If calling the adapter directly, check that the target peer is online and its public_endpoint is reachable.

Cause: The telemetry endpoint requires a proxy_token Bearer — not the node_token used for heartbeat/deregister. The proxy_token is a separate 40-byte token issued at registration. Error code: IICP-E032.

Fix: Use the proxy_token returned in the registration response (not node_token). The proxy_token is stored separately and must not be reused as a node_token. If the proxy_token was lost, re-register the node to obtain a fresh pair.

Cause: The credit amount claimed in the CIPWorkerReceipt exceeds the authorized ceiling: ceil(tokens_used / 1000) × credit_cost_multiplier × 1.1. This prevents credit inflation attacks (TC-9c). Error code: IICP-E027.

Fix: Verify the amount field matches the actual tokens consumed at the node's pricing rate. The ceiling is enforced before the nonce is consumed, so you may retry with a corrected amount and the same nonce.

Cause: The nonce in the CIPWorkerReceipt has already been used. Each award request must supply a unique nonce. The directory uses an atomic lock to reject duplicate submissions within the receipt's validity window (TC-9d). Error code: IICP-E027.

Fix: Generate a fresh nonce for each award request. If the original request was lost in transit, check the credit balance via GET /api/v1/credits/balance before retrying — the original may have been applied.

Cause: The node has exceeded the per-hour credit award rate limit (1 000 credits/hour per node_id). This is an anti-laundering control (TC-9b, S.12 §10.6) that caps the rate at which a single node can earn credits, preventing colluding nodes from inflating balances through circular task routing. Error code: IICP-E027.

Fix: Wait for the hourly window to reset before submitting additional award requests. The rejected request does not consume the nonce — you may retry the same receipt after the window resets. If you legitimately process a high volume of tasks, contact the directory operator to request a higher rate limit.

Cause: The declaration_signature in the pricing block does not match the HMAC-SHA256 of the pricing fields. Signature is required when credit_cost_multiplier is supplied. Error code: IICP-E010.

Fix: Recompute the declaration_signature using HMAC-SHA256 over the canonical pricing JSON with the node_hmac_key issued at registration. Ensure no extraneous whitespace in the signed fields.

Cause: An event received from the Genesis Seed failed Ed25519 signature verification. The event is discarded and the operator is alerted. Error code: IICP-E013 (DIR-FED-01/04).

Fix: Check that the Genesis Seed DID document at /.well-known/did.json has not been rotated. If a key rotation occurred, re-fetch the DID document and re-verify the event history. Do not apply unverified events.

Cause: A non-monotonic sequence number was detected in the Genesis Seed event stream — a gap or replay in the seq field. Sync is halted. Error code: IICP-E014 (DIR-FED-02).

Fix: Re-fetch from since_seq equal to the last valid seq. If the gap persists, contact the Genesis Seed operator. The replica MUST NOT serve discovery until sync resumes (DIR-FED-08).

Cause: The consumer proxy attempted cooperative inference dispatch but found no eligible CIP workers — either no nodes with allow_remote_inference=true in the current discovery cache, or all candidates are below min_reputation. Error code: IICP-E022 (S.12 §2.2).

Fix: Verify CIP-capable nodes are registered and active (GET /api/v1/discover?view=public&intent=<urn> — check cip_policy.allow_remote_inference in results). If the network has no CIP providers, enable local execution fallback in your client config.

Cause: The directory was reachable and returned zero candidate nodes for this intent after filtering (intent URN, region, reputation). Distinct from no_available_node, which means nodes were returned but all routing attempts failed at runtime. Error code: IICP-E033.

Fix: 1) Verify the intent URN is correct and registered — check /registry for the canonical intent list. 2) Check /nodes to see which providers are currently active and which intents they advertise. 3) If the intent is correct and providers exist, they may be temporarily offline — wait for the next heartbeat cycle (60 s) and retry. 4) If no providers exist for this intent, you may need to run a provider node or contact the network operator.

Cause: A CIPWorkerReceipt award request arrived for a node that has no HMAC key provisioned. The directory cannot verify the receipt signature without the key. Error code: IICP-E027.

Fix: Re-register the node to provision a fresh node_hmac_key. The HMAC key is issued at registration and stored server-side — it cannot be re-provisioned without a full re-registration.

Cause: A CIP CALL contained an invalid field value. Four distinct triggers: (1) Coordinator path — cip.policy not one of best_of_n, majority_vote, map_reduce; cip.replicas outside [1, 10]; or cip.quorum not null and out of range. (2) Adapter/Rust worker path — trace.cip_role is present but not 'coordinator' or 'worker'. (3) Adapter/Rust worker path — cip.cip_parent_task_id is present but not a valid UUID v4. (4) Rust worker path — cip.cip_role is present in the cip envelope but not 'worker' (the cip envelope is sent by a coordinator to tell the worker its role; any value other than 'worker' is malformed). All four triggers return 422 at parse time. Error code: IICP-E028 (S.12 §4.1 + §4.2).

Fix: Identify which trigger fired from the error message. For coordinator validation: check cip.policy (must be exact string), cip.replicas (integer 1–10), cip.quorum (positive integer ≤ replicas or null). For trace.cip_role: must be 'coordinator' when the request originates from a coordinator, or 'worker' when forwarding a sub-task — any other string is invalid. For cip.cip_parent_task_id: must be a UUID v4 string (e.g. generated by uuid4()); UUID v1/v3/v5 and malformed strings are rejected. For cip.cip_role in the cip envelope: must be 'worker' — the coordinator sets this to tell the recipient it is the worker in the CIP sub-task.

Cause: A majority_vote CIP CALL specified an invalid replica count. For majority_vote, cip.replicas must be an odd integer ≥ 3 (a majority decision requires at least 3 voters, and an even number produces a tie). Error code: IICP-E025 (S.12 §3.2).

Fix: Use an odd replica count ≥ 3 for majority_vote: 3, 5, 7, or 9 (maximum 9 for majority_vote, since the global ceiling is 10). If you do not need quorum semantics, switch to best_of_n, which accepts any replica count in [1, 10].

Cause: The endpoint URL in POST /v1/register resolves to a non-routable address: localhost, 127.0.0.0/8, ::1, RFC1918 (10/8, 172.16–172.31/12, 192.168/16), 169.254/16 link-local, or a reserved suffix (.local, .test, .example, .invalid, .lan, .internal), or a bare hostname with no TLD (e.g. a Docker-compose service name). The directory rejects these because other mesh participants cannot reach them. Error code: IICP-E035.

Fix: Register with a publicly-routable DNS hostname or IP address. For local development, run a local directory instance with APP_ENV=local (which bypasses this check). For production, expose a port via Cloudflare Tunnel, ngrok, or a VPS — see /docs/port-forwarding for options.

Cause: The consumer proxy ran the pre-dispatch credit check before routing a task and found the S-Credit balance below the computed routing cost (ceil(output_tokens/1000) × tier_weight × multiplier). The proxy aborts without dispatching to avoid a failed charge mid-flight. Error code: IICP-E036.

Fix: Check your credit balance: iicp-node credits (CLI) or GET /api/v1/credits/balance. Earn credits by enabling CIP worker mode (allow_remote_inference = true in your node config) and serving inference tasks. If you have sufficient credits and still see this error, verify that IICP_NODE_TOKEN is set correctly for the node that holds the balance.