{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "docsrs-cli JSON error envelope",
"type": "object",
"description": "Top-level JSON written on failure when JSON output is selected. Not nested under data. Camada Y: top-level command + duration_ms match success envelopes for agent correlation.",
"required": ["schema_version", "ok", "command", "duration_ms", "error"],
"additionalProperties": false,
"properties": {
"schema_version": {
"type": "integer",
"const": 1
},
"ok": {
"type": "boolean",
"const": false
},
"command": {
"type": "string",
"description": "Wire command name (get-item, search-crates, usage, cache-path, …). usage when clap fails before dispatch."
},
"duration_ms": {
"type": "integer",
"minimum": 0,
"description": "Wall-clock duration of the attempt in milliseconds (0 for early parse/config failures)"
},
"error": {
"type": "object",
"required": ["code", "kind", "message", "retryable"],
"additionalProperties": false,
"properties": {
"code": {
"type": "integer",
"minimum": 0,
"maximum": 255,
"description": "Process exit code"
},
"kind": {
"type": "string",
"enum": [
"usage",
"invalid_input",
"not_found",
"rate_limited",
"unavailable",
"timeout",
"network",
"budget",
"parse",
"config",
"io",
"internal",
"broken_pipe",
"canceled"
],
"description": "Stable snake_case ErrorKind discriminant on the wire. Enumerated here as well as described, because a description is prose and a validator cannot reject a kind that only prose forbids. budget = local body/output budget exceeded (exit 74, retryable=false). io = local filesystem failure caused by the environment (exit 74); retryable reflects the OS cause, so a full disk is retryable and a permission denial is not. Exit 74 is shared by network, budget and io and is ambiguous until this field is read. canceled covers SIGINT/SIGTERM (exit 130/143); internal Interrupted/Terminated map to canceled on the wire."
},
"message": {
"type": "string",
"description": "Technical English message (never secrets)"
},
"retryable": {
"type": "boolean",
"description": "True only for transient failures (rate_limited, unavailable, timeout, network, and io when the OS cause can clear). budget is permanent for the same config. For io the answer comes from the underlying errno, not from the kind: ENOSPC is retryable and EACCES is not, and both arrive as kind=io at exit 74."
},
"retry_after_secs": {
"type": "integer",
"minimum": 0,
"description": "Omitted when absent; never JSON null"
},
"suggestions": {
"type": "array",
"minItems": 1,
"description": "Ranked --suggest alternatives, best first. Present only on a not-found whose recovery ladder produced at least one candidate; omitted otherwise, never JSON null and never an empty array. The same list is also spelled into message for humans — read it here instead of splitting that sentence apart.",
"items": {
"type": "object",
"required": ["path", "kind"],
"additionalProperties": false,
"properties": {
"path": {
"type": "string",
"description": "Item path to retype (option::Option::unwrap), without the crate prefix"
},
"kind": {
"type": "string",
"description": "CLI kind to pass alongside path (method, variant, struct, …). This is the kind the caller would retype, not the rustdoc anchor family: labelling an associated type as method would send them back into the same not-found."
}
}
}
}
}
}
}
}