# Errors

Every error code the API and MCP server return, what it means and what to do.

| Status | Code | Meaning and what to do |
| --- | --- | --- |
| 400 | `bad_request` | An input is invalid. `field` names it; `details` lists each problem. |
| 401 | `unauthorized` | No token, or unknown, revoked or expired. OAuth: refresh or reconnect. Personal: create a new one. |
| 403 | `insufficient_scope` | The token lacks the scope the operation needs. |
| 403 | `role_insufficient` | The person's role on this Concierge does not allow it (publishing needs admin). |
| 403 | `account_suspended` | The account is paused (email not confirmed, payment, or a rules violation). The person signs in to Studio to fix it. |
| 403 | `plan_limit` | The plan does not include this or is full; `details` has the limit. |
| 403 | `agent_disabled` | The Concierge was disabled by the platform; nothing can change it until it is re-enabled. |
| 404 | `agent_not_found` | Unknown agent, or not reachable with this token. |
| 404 | `draft_not_found`, `version_not_found`, `test_run_not_found` | Unknown id for this agent. List them first. |
| 409 | `draft_closed` | The draft was already applied or discarded. Create a new one. |
| 409 | `confirmation_required` | Sensitive write: ask the person, then retry with `confirm: true`. |
| 409 | `version_conflict` | The agent changed since you read it. Read again, then redo the change. |
| 409 | `idempotency_in_progress` | The first call with this key is still running. Retry shortly. |
| 422 | `idempotency_key_reused` | Same key, different input. Use a new key. |
| 422 | `not_ready` | Something required is missing before publishing; the message says what. |
| 422 | `changes_invalid` | A change set does not fit the configuration schema; `details` lists each problem. Check `get_configuration_schema`. |
| 422 | `version_unrestorable` | That version cannot be restored (for example it no longer fits the schema). |
| 429 | `rate_limited` | Wait `Retry-After` seconds. |
| 500 | `internal` | Our side. Retry later; quote `requestId` if it continues. |

## OAuth endpoints

`/oauth/token`, `/oauth/register` and `/oauth/revoke` answer in RFC 6749 form: `{"error": "...", "error_description": "..."}`, with `invalid_request`, `invalid_client` (401), `invalid_grant`, `unsupported_grant_type`, `invalid_redirect_uri` or `invalid_client_metadata`.