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