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 |
Meaning and likely cause |
Recommended action |
|---|---|---|---|
|
|
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) |
|
|
Multiple authentication credentials sent in one request (for example both |
Send exactly one credential; use a dedicated API client with cookies disabled for this path, see Troubleshoot failed calls |
|
|
Missing workspace identifier |
Include a valid |
|
|
Missing, expired, or revoked credential, or sending an AI Studio personal access token via |
Send personal access tokens to AI Studio endpoints via |
|
|
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 |
|
|
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 |
|
|
Duplicate name/key, incompatible lifecycle state, or dependent bindings present (including |
Use a unique name, resolve state transitions, or detach bound workflows/services before deleting |
|
|
Concurrency or request rate limit exceeded for published workflow/operator services |
Reduce client concurrency and retry with exponential backoff |
|
|
Unexpected server error |
Record timestamp, request path, and response payload, then contact Support and feedback |
|
|
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 |
Meaning and resolution |
|---|---|---|
|
|
Invalid sandbox name, compute spec, or disk size value |
|
|
Egress allowlist entry is not formatted as |
|
|
Network allowlist configuration or unrestricted network mode is disabled in this deployment |
|
|
Caller lacks permission to access or administer the managed sandbox |
|
|
Managed sandbox or target compute resource does not exist |
|
|
Workspace reached its managed or ephemeral sandbox limit; delete idle managed environments or ask a platform admin to adjust workspace quota |
|
|
Target compute resource cannot bind sandboxes, workspace deletion is active, or manual recovery is needed |
|
|
Conversation workspace checkpoint/recovery conflict; complete save/recovery before provisioning again |
|
|
Downstream IAM, token binding, or network storage unavailable; retry shortly |
|
|
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 |
Meaning and recommended action |
|---|---|---|
|
|
Invalid field (see |
|
|
Missing/expired/revoked credential or service account lacks execution permission; send |
|
|
Insufficient account Credit; recharge in Top Up Credit and retry |
|
|
Model ID is unknown, disabled, or outside your account/plan allowlist; verify via List models |
|
|
HTTP payload exceeds gateway byte cap; chunk files or shrink request payload |
|
|
Credential RPM/TPM/concurrency cap reached or all upstream model providers rate-limited; respect the |
|
|
Upstream model providers failed or account rate-limit policy store is unavailable; save |
MatrixOne instance and SQL troubleshooting pointers¶
When connecting directly to a MatrixOne instance or querying through AI Studio:
Connection timeout or refused: Verify the instance state is running, check public/private endpoint host and port, confirm IP allowlists permit your egress IP, and verify TLS settings (Database instances).
Authentication or privilege denial: Check
username:role_namelogin formatting and tenant-scopedGRANTassignments (Permissions: MatrixOne and SQL privilege categories).SQL syntax or import limits: Consult SQL limitations and SQL Editor.