Errors
One page for every error code. Each error response links to its page from its type member.
| Code | Status | Retryable | Meaning |
|---|---|---|---|
| invalid_request | 400 | No | Malformed body, unknown field, bad type |
| version_required | 400 | No | No `Melro-Version` header |
| unsupported_version | 400 | No | Unknown or sunset API version; lists supported versions |
| invalid_cursor | 400 | No | Cursor malformed, expired or not valid for this caller or query |
| invalid_api_key | 401 | No | Key missing, malformed, unknown |
| key_expired | 401 | No | As named |
| key_revoked | 401 | No | As named |
| key_suspended | 403 | No | Suspended by Melro staff |
| scope_not_granted | 403 | No | Names the scope required |
| version_not_allowed | 403 | No | Published version not in the workspace allowlist or key narrowing |
| release_not_selectable | 403 | No | A live key named a Melro release, or a test key asked for Preview on a handle not validated on it |
| access_restricted | 403 | No | Organization restricted; no cause given |
| not_found | 404 | No | Non-enumerating |
| idempotency_conflict | 409 | No | Same key, different request (replaces `request_conflict`, `key_conflict` on public surfaces) |
| request_in_progress | 409 | Yes | The first request with this key has not finished |
| stale_revision | 409 | No | `If-Match` or expected revision is not current |
| version_retired | 409 | No | A published version the customer retired, named by a new request, in every API |
| release_retired | 409 | No | Melro release axis only: the Melro release the pair runs on is retired |
| package_unsupported | 409 | No | Melro release axis only: the actor version's package schema major is retired |
| gone | 410 | No | Erased; tombstone kept |
| too_large | 413 | No | Body or transcript over the published limit |
| wrong_home | 421 | Yes | Use the host named in the `host` member |
| invalid_parameters | 422 | No | Start parameters unknown or out of range |
| notice_required | 422 | No | Voice Start without the customer's notice attestation |
| unsupported_input | 422 | No | Input the owner refuses by product rule (language, speaker roles); `errors[].rule` says which |
| rate_limited | 429 | Yes | Request or command rate over the limit (Voice steering 5 per second [VP-47]) |
| concurrency_limit_reached | 429 | Yes | Concurrent sessions or in-flight runs at the caller's limit |
| test_cap_reached | 429 | No | Test usage cap reached; `resets_at` when known |
| spend_limit_reached | 429 | No | Workspace hard spend limit (Launch); `resets_at` when known |
| internal_error | 500 | Yes | Unexpected |
| capacity_unavailable | 503 | Yes | Melro at capacity; admission order applied (PAS-10.3) |
| tier_unavailable | 503 | Yes | The pinned tier's provider is unavailable |
| dependency_unavailable | 503 | Yes | A Melro dependency is unavailable |
| authority_unavailable | 503 | Yes | Access cannot decide; never treated as allow (replaces `unavailable` in WP-AX-04 §3.6; Insights' `authority_unavailable` unchanged) |
| recovery_in_progress | 503 | Yes | Owner recovering; covers `key_reverification_pending` and Insights `recovery_gap` |
| report_expired | 410 | No | The authorized Insights report snapshot is past its life. |
| incomplete_data | 422 | No | The requested report cannot be answered at the required completeness. |
| query_too_large | 422 | No | The report exceeds the published query envelope. |
| version_not_installed | 409 | Yes | The actor handle installation is pending or was refused. Retry only after the install outcome permits a new attempt. |
| launch_grant_invalid | 401 | No | Training launch grant expired, replayed, wrong audience or unknown/revoked signing key. |
| payment_required | 403 | No | A local commercial restriction for payment failure, dispute or chargeback. |
| balance_exhausted | 403 | No | Local funded balance is below the admission threshold; never ends an active session. |
| commercial_restriction | 403 | No | A locally applied staff commercial restriction or an unrecognized commercial reason blocks admission. |
| engine_release_retired | 409 | No | The selected Scoring engine release has retired. |
| purchased_quantity_reached | 403 | No | Training purchased quantity is exhausted at new practice admission; never ends a running call. |
| unauthenticated | 401 | No | The session/person-delegated authentication is invalid, expired or for the wrong owner. |
| context_not_established | 409 | No | The staff session has not established its staff organization context. |
| permission_not_granted | 403 | No | The authenticated person, or the person bound to an authoring key, lacks the required current role or owner-local permission. Do not disclose an invisible resource or relabel a common restriction as a known role failure. |
| agent_not_permitted | 403 | No | A person-only operation has an agent label or its declared vendor lacks the required approved entry. |
| fresh_sign_in_required | 401 | No | The operation requires a sufficiently recent sign-in under its owner contract. |
| confirmation_required | 422 | No | A consequential agent-labelled request lacks its required matching confirmation. |
| prerequisite_missing | 422 | No | A visible prerequisite record or evidence is absent or not in the required state. |
| invalid_state | 409 | No | A visible resource state does not permit this command. |
| hold_active | 409 | No | The existing approval hold has not ended; time alone does not grant authority. |
| mapping_conflict | 409 | No | An already-visible Plain thread mapping conflicts with the requested organization. |
| confirmation_expired | 409 | No | Prepared Workbench confirmation expired; prepare and confirm again. |
| creator_confirmation_required | 403 | No | The action needs a tap by a person who holds the right to commit it at commit time; never a model or an authoring key. The person need not be the preparer. |
| knowledge_conflict | 409 | No | Pinned knowledge has an unresolved conflict that blocks this new attestation. |
| knowledge_unconfirmed | 409 | No | Pinned knowledge needs confirmation before this new attestation. |
| knowledge_withdrawn | 409 | No | Pinned knowledge was withdrawn; no new attestation may use it. |
| limit_exceeded | 422 | No | A persistent owner inventory/storage ceiling is reached; identify limit_name; not a transient rate limit. |
| workspace_required | 422 | No | An explicit organization/workspace selection is required before this action. |
| unsupported_comparison | 409 | No | Requested meaning/version populations cannot be compared; preserve distinct releases/populations. |
| report_invalidated | 409 | No | Authorized immutable report cut is no longer eligible for disclosure; a permitted new query is a new explicit intent. |
| already_complete | 409 | No | Export cancellation lost to the ready commit; inspect the existing job, never report cancellation. |
| artifact_not_ready | 409 | Yes | Authorized export has no committed ready artifact; poll status with bounded backoff while nonterminal. This code never retries job creation or implies delivery authorization. |
| artifact_expired | 410 | No | Authorized export artifact expired; its job identity and recorded completion do not become new work. |
| approval_required | 409 | No | A Scoring specification publication lacks a valid effective approval (errors[].rule approval_missing or approval_incomplete). |
| revision_exists | 409 | No | The same revision content hash already belongs to another specification in the same original source scope (errors[].rule revision_exists_in_other_specification); errors[].detail carries the visible spec_id and revision_id. A specific code, not a generic conflict. |