# 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.

```json
{
  "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.
