Every error of the API answers an HTTP status and a body listing the errors found. A request that does not resolve reports all its errors at once (every missing input, every invalid argument), not the first one only.
{
"errors": [
{
"code": "tc::missing-instance",
"message": "component `tcu` has several instances",
"help": "give one of: TCU1, TCU2, TCU3"
},
{
"code": "tc::unexpected-argument",
"message": "telecommand `ping` has no argument `voltage`"
}
]
}| Field | Content |
|---|---|
code | Stable identifier, <domain>::<name>. Clients match on it, never on the message. |
message | Explanation for the operator, naming what is wrong. |
help | Optional suggested fix. |
The same codes appear in the CLI, which prints the messages of the API. The status gives the family:
| Status | Meaning |
|---|---|
400 | The request itself is malformed: body, identifier, selector, missing operator identity for a command |
401 | Identity refused or required by the environment |
403 | Identified, but not allowed: not a feeder, not a supervisor |
404 | Unknown route, target, run, pass, schedule, transfer, instance, or invalid path parameter |
409 | Refused by the current state: target held by a run (telecommand or mode), pass not usable, run not running, alarm command refused, schedule already final |
413 | Content too large |
422 | The request does not resolve against the configuration, or breaks a policy |
502, 503, 504 | A service behind the API is missing, unreachable or did not answer |
API#
| Code | Status | Meaning |
|---|---|---|
api::unknown-route | 404 | No such route in this version of the API |
api::invalid-body | 400 | The body is not valid JSON of the expected shape (unknown field, wrong type) |
api::invalid-id | 400 / 404 | Not a ULID: 400 for the id of a submission, 404 for a path parameter |
api::invalid-target | 404 | The target in the path is not a valid name |
api::invalid-alarm | 404 | Not an alarm such as tcu[TCU1].anode_voltage |
api::invalid-measure | 400 | Not a measure selector such as tcu[TCU1].responding |
api::invalid-instance | 404 | The instance in the path is not a valid name |
api::unknown-target | 404 | No such target in the current configuration |
api::unknown-environment | 422 | GET /v1/targets/{target}/parameters?environment=…: the target is not engaged in that environment |
api::unknown-instance | 404 | No such registered instance |
api::unknown-command | 404 | Not a command of the route (suspend, resume, abort; acknowledge, shelve, unshelve) |
api::anonymous | 400 / 401 | No identity: 400 for a command that needs the name of the operator, 401 where the environment requires one |
api::no-configuration | 503 | No compiled configuration published yet (stellar compile --publish) |
api::no-catalogue | 503 | The catalogue of the target is missing from the current snapshot |
api::unavailable | 503 | The bus (NATS, JetStream) is unavailable |
Identity#
| Code | Status | Meaning |
|---|---|---|
auth::invalid-token | 401 | The bearer token is refused: signature, expiry, issuer, audience or subject |
auth::no-provider | 401 | A token was given but no identity provider is configured (auth.jwks_url, auth.jwks_file) |
auth::token-required | 401 | auth.required: every request needs an OIDC token, declared identities are refused |
auth::jwt-required | 401 | The environment requires an OIDC token (identity: jwt): declared identities are refused; also for POST /v1/auth/nats |
auth::invalid-key | 400 | public_key is not the public nkey of a user |
auth::no-signing-key | 503 | The API has no account signing key to issue NATS credentials |
Telecommands#
POST /v1/tc and POST /v1/targets/{target}/files/refresh resolve the telecommand against the
current configuration. An unknown target answers 404; every other resolution error 422.
| Code | Status | Meaning |
|---|---|---|
tc::unknown-target | 404 | No such target |
tc::missing-catalogue | 422 | The catalogue of the target is not in the snapshot |
tc::unknown-link | 422 | The target has no such link |
tc::unknown-environment | 422 | The target is not engaged in that environment |
tc::environment-required | 422 | The link has parameters by environment and the target is engaged in several: name the environment |
tc::link-component | 422 | The link does not carry the component of the telecommand |
tc::unknown-telecommand | 422 | The platform has no such telecommand |
tc::ambiguous-telecommand | 422 | Several components have a telecommand of that name: write component.name |
tc::missing-instance | 422 | The component has several instances: give one |
tc::unexpected-instance | 422 | The component has a single instance |
tc::unknown-instance | 422 | The component has no such instance |
tc::unexpected-argument | 422 | The telecommand has no such argument |
tc::missing-argument | 422 | An argument has no value and no default |
tc::invalid-argument | 422 | Wrong type, unit or enum value |
tc::out-of-range | 422 | The value is outside the range of the argument |
tc::target-held | 409 | The target is held by a run: direct telecommands wait for its end (a changes_state: false telecommand passes a shared lease) |
Runs#
POST /v1/runs resolves the run request (422 with every error), then checks the passes (409).
| Code | Status | Meaning |
|---|---|---|
run::unknown-environment | 422 | No such environment |
run::unknown-library | 422 | No such library |
run::unknown-procedure | 422 | No such procedure |
run::ambiguous-procedure | 422 | Several libraries have a procedure of that name: give library |
run::not-allowed | 422 | The procedure is not allowed in the environment (allowed in) |
run::draft-not-allowed | 422 | A draft library or catalogue, refused where allow_draft is off |
run::unexpected-target | 422 | The procedure has no such role |
run::missing-target | 422 | A role has no target |
run::unknown-target | 422 | No such target, or its catalogue is not in the snapshot |
run::wrong-platform | 422 | The target does not implement the platform of its role, nor imports components of it |
run::catalogue-version | 422 | The target implements (or imports) another version of the catalogue than the one the library was compiled against |
run::not-imported | 422 | The procedure uses a component of the package of its role that the platform of the target does not import |
run::target-not-in-environment | 422 | The target is not engaged in the environment |
run::unexpected-input | 422 | The procedure has no such input |
run::missing-input | 422 | An input has no value |
run::invalid-input | 422 | Invalid value for an input (type, unit, enum) |
run::unknown-link | 422 | A link named by via or link[…] does not exist on the target |
run::fault-target, run::fault-step, run::fault-not-simulated | 422 | A scheduled fault (faults) names no role of the run, or a step it never enters, or is requested in in_orbit |
run::link-component | 422 | A telecommand goes through a link that does not carry its component |
run::plan-required | 422 | The procedure sends a hazardous telecommand: in this environment it must be planned on a pass |
run::must-be-scheduled | 422 | Such a run starts from a schedule only (POST /v1/schedules) |
run::parameter-undefined | 422 | A configure … for <mode> or param … in <mode> reads a parameter that has no value on the target in that mode |
run::unknown-pass | 422 | plan names no pass of a target of the run |
run::pass-cancelled | 409 | The pass is cancelled |
run::not-booked | 409 | In in_orbit, only a booked pass carries a run |
run::before-aos | 409 | The pass has not started yet |
run::window | 409 | The run may end after LOS minus scheduler.margin |
run::receive-only | 409 | The pass has no uplink and the run sends telecommands |
run::no-link | 409 | In in_orbit, a manual run needs the default link of each target bound and available |
run::unknown | 404 | No such run |
run::not-running | 409 | No executor holds the run: it is over, or not started |
run::refused | 409 | The executor refused the command (for instance, resuming without leases or ready targets) |
run::timeout | 504 | The executor did not answer |
Modes#
PUT /v1/targets/{target}/mode declares the mode of a target; see
Modes and Parameters.
| Code | Status | Meaning |
|---|---|---|
mode::unknown | 422 | The topology declares no such mode |
mode::target-held | 409 | A run holds the target: its runs set its mode |
api::anonymous (400) answers a PUT without the identity of the operator,
api::unknown-target (404) an unknown target.
Alarms#
| Code | Status | Meaning |
|---|---|---|
alarm::refused | 409 | Nothing to acknowledge, alarm not shelved or never recorded, shelving duration out of bounds |
alarm::no-service | 503 | No alarm service is running |
alarm::timeout | 504 | The alarm service did not answer |
Passes#
| Code | Status | Meaning |
|---|---|---|
pass::not-a-feeder | 403 | The caller is not a feeder of passes.feeders |
pass::forbidden-source | 403 | The feeder writes the passes of another source |
pass::invalid | 422 | Invalid body or pass: window, elevation, rates, a fds pass booked… |
pass::unknown-target | 422 | No such target in the current configuration |
pass::unknown | 404 | No such pass |
Schedules#
| Code | Status | Meaning |
|---|---|---|
schedule::invalid | 422 | Invalid body of a schedule or a rule |
schedule::refused | 422 | Refused: it would not be scheduled (window, booking, uplink, start in the past), its request does not resolve, or a rule runs a hazardous telecommand |
schedule::unknown | 404 | No such schedule |
schedule::unknown-rule | 404 | No such rule |
schedule::final | 409 | The schedule is already fired, missed or cancelled |
schedule::changed | 409 | The schedule changed meanwhile: try again |
schedule::not-supervisor | 403 | Only a supervisor validates a plan |
Files and transfers#
| Code | Status | Meaning |
|---|---|---|
files::no-directory | 404 / 422 | The platform of the target has no on-board directory (files component) |
files::no-listing | 422 | The platform declares no listing telecommand (transfer.list) |
transfer::invalid | 422 | Invalid transfer request |
transfer::not-listed | 422 | The file was never listed: refresh the directory first |
transfer::unknown | 404 | No such transfer |
Simulation and editor#
| Code | Status | Meaning |
|---|---|---|
sim::unknown-gateway | 404 | No simulated gateway of that name answers |
sim::not-simulated | 422 | The gateway is not a simulated one |
sim::refused | 422 | The simulator refused: unknown fault… |
sim::timeout | 504 | The gateway did not answer |
editor::disabled | 404 | No editor service behind this API (api.editor_url) |
editor::too-large | 413 | Request too large for the editor |
editor::unreachable | 502 | The editor service does not answer |