Error Codes and Status Reference

This page summarizes common error codes, HTTP status codes, and resolution paths across the MatrixOne Intelligence (MOI) REST APIs, Genesis model gateway, agent runtime sandboxes, and MatrixOne database instances. For endpoint-specific responses, check the action pages in API reference; for console and workflow symptom guides, see Troubleshooting and FAQ.

MOI / AI Studio HTTP API error envelope

AI Studio workspace and administration APIs return a standard JSON error envelope (exact optional fields follow each action page):

{
  "code": "ErrParamInvalid",
  "msg": "readable localized message"
}

Common HTTP and business error codes

HTTP status

Common code

Meaning and likely cause

Recommended action

400

ErrParamInvalid

Missing required parameter, invalid field format, malformed JSON, or unsupported fields

Verify required fields, data formats, and payload limits (typically 1 MiB for JSON config bodies)

400

ErrMultipleAuthCredentials

Multiple authentication credentials sent in one request (for example both X-API-Key and Authorization: Bearer, or saved browser cookies sent alongside an API key)

Send exactly one credential; use a dedicated API client with cookies disabled for this path, see Troubleshoot failed calls

400

ErrWorkspaceRequired

Missing workspace identifier

Include a valid X-Workspace-ID header

401

ErrUnauthorized, ErrUnauthenticated, Unauthorized, unauthenticated

Missing, expired, or revoked credential, or sending an AI Studio personal access token via Authorization: Bearer

Send personal access tokens to AI Studio endpoints via X-API-Key; refresh expired terminal tokens

403

ErrForbidden

Insufficient workspace role permissions, missing configured administrator identity, or missing valid browser session CSRF token

Check member roles under Role permissions; admin routes require administrator identity

404

ErrNotFound

Target resource ID, sandbox, or history item does not exist or is not visible in the specified workspace

Verify the resource ID matches the target X-Workspace-ID

409

ErrAlreadyExists, ErrDuplicateName, ErrDuplicateKey, ErrConflict

Duplicate name/key, incompatible lifecycle state, or dependent bindings present (including workflow_rerun_conflict, rerun_contract_mismatch, api_service_disabled)

Use a unique name, resolve state transitions, or detach bound workflows/services before deleting

429

ErrDynamicServiceConcurrencyLimit, ErrDynamicServiceRateLimit

Concurrency or request rate limit exceeded for published workflow/operator services

Reduce client concurrency and retry with exponential backoff

500

ErrServer

Unexpected server error

Record timestamp, request path, and response payload, then contact Support and feedback

503 / 502

ErrServiceUnavailable

Authorization service, preferences store, or upstream infrastructure temporarily unavailable

Retry with backoff and check upstream service availability

Sandbox and runtime environment error codes

HTTP status

Error code

Meaning and resolution

400

SANDBOX_INVALID_NAME, SANDBOX_INVALID_SPEC

Invalid sandbox name, compute spec, or disk size value

400

SANDBOX_EGRESS_INVALID_HOST, SANDBOX_EGRESS_MISSING_PORT, SANDBOX_EGRESS_INVALID_PORT, SANDBOX_EGRESS_HOST_LIMIT_EXCEEDED, SANDBOX_EGRESS_PORT_LIMIT_EXCEEDED

Egress allowlist entry is not formatted as domain:port or exceeds host/port count limits

400

SANDBOX_NETWORK_ALLOWLIST_UNAVAILABLE, SANDBOX_NETWORK_UNRESTRICTED_DISABLED

Network allowlist configuration or unrestricted network mode is disabled in this deployment

403

SANDBOX_FORBIDDEN

Caller lacks permission to access or administer the managed sandbox

404

SANDBOX_NOT_FOUND, SANDBOX_COMPUTE_RESOURCE_NOT_FOUND

Managed sandbox or target compute resource does not exist

409

SANDBOX_QUOTA_EXCEEDED

Workspace reached its managed or ephemeral sandbox limit; delete idle managed environments or ask a platform admin to adjust workspace quota

409

SANDBOX_COMPUTE_RESOURCE_NOT_BINDABLE, SANDBOX_WORKSPACE_DELETING, SANDBOX_REQUEST_CONFLICT, SANDBOX_MANUAL_RECOVERY_REQUIRED

Target compute resource cannot bind sandboxes, workspace deletion is active, or manual recovery is needed

409

SESSION_WORKSPACE_CONFLICT, SESSION_WORKSPACE_NOT_SAVED, SESSION_WORKSPACE_RECOVERY_INCOMPLETE

Conversation workspace checkpoint/recovery conflict; complete save/recovery before provisioning again

503

SANDBOX_IAM_UNAVAILABLE, SANDBOX_CREDENTIAL_UNAVAILABLE, SANDBOX_NETWORK_STORAGE_UNAVAILABLE

Downstream IAM, token binding, or network storage unavailable; retry shortly

500

SANDBOX_ERROR

Unclassified sandbox runtime or provider error; record environment ID and timestamp for support

Genesis model gateway and service-account errors

Genesis data-plane endpoints return an OpenAI-compatible error object with a traceable request_id:

{
  "error": {
    "message": "insufficient credit",
    "type": "billing_error",
    "param": "",
    "code": "insufficient_credit",
    "request_id": "..."
  }
}

HTTP status

Common error.code

Meaning and recommended action

400

invalid_request, provider_schema_error, context_length_exceeded

Invalid field (see error.param), unsupported request shape, or prompt exceeds the model context window; shorten input or select a larger-context model

401 / 403

invalid_api_key, authentication_error, permission_error

Missing/expired/revoked credential or service account lacks execution permission; send Authorization: Bearer <sk-uca-v1 | sk-sa-v1 | sk-mo> (never cookies or admin JWTs)

402

insufficient_credit

Insufficient account Credit; recharge in Top Up Credit and retry

404

model_not_found

Model ID is unknown, disabled, or outside your account/plan allowlist; verify via List models

413

request_body_too_large

HTTP payload exceeds gateway byte cap; chunk files or shrink request payload

429

rate_limit_exceeded, all_providers_rate_limited

Credential RPM/TPM/concurrency cap reached or all upstream model providers rate-limited; respect the Retry-After response header

502 / 503

upstream_error, account_rate_limits_unavailable

Upstream model providers failed or account rate-limit policy store is unavailable; save request_id and retry later

MatrixOne instance and SQL troubleshooting pointers

When connecting directly to a MatrixOne instance or querying through AI Studio:

Last updated on