Errors, permissions, and environments

HTTP / code

Verified branch

400 / 2

Invalid parameters/candidate. ErrAgentReadOnly for ineligible same-Workspace binding currently also maps to 400 through the default skill error branch; do not automatically document 403.

404 / 3

Some branches where the original task, owner, manifest, native candidate, or skill reference is unavailable. The message uses skill not found without exposing the missing internal layer.

409 / 4

A duplicate conflict, such as an existing reserved ID whose content digest or creator does not match.

409 / 9 with a binding failure reason

The skill was saved, but subsequent binding failed. Use reason/domain/saved_skill_id for recovery; code9 alone cannot distinguish every conflict.

403 / 5

Skill read-only or authorization rejection. Binding-stage rejection may also be wrapped as a 409 save-then-bind failure.

503 / 15

Authorization or skill dependency unavailability. Not every binding failure passes through 503.

500 / 1

Explicit branches such as binding-error localization failure. saved_skill_id is not guaranteed in these cases.

Success uses numeric code0/data. Ordinary skill errors use code/message; binding failures add details. Identity validation precedes the handler and may use string code/msg; do not normalize these to numeric errors. Unknown errors may currently map to 400 with error text through the default skill error branch; do not assume uniform 500.

{
  "code": 9,
  "message": "The skill was saved, but could not be added to this agent. Retry to finish adding it.",
  "details": {
    "reason": "SKILL_CREATOR_BINDING_FAILED",
    "domain": "moi-core.catalog.agent-resource",
    "saved_skill_id": "skill-example"
  }
}

message follows the server language; the example uses an en-US catalog value. Identify binding failure with details.reason, not localized message matching. After any error or timeout with uncertain save status, query the original candidate first.

Last updated on