# 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](api/index.md); for console and workflow symptom guides, see [Troubleshooting and FAQ](../get-started/troubleshooting.md).

## 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):

```json
{
  "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](../developer/quickstart/ai-studio/http-api.md#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](../guides/ai-studio/permissions/roles.md); 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](../get-started/support.md) |
| `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`:

```json
{
  "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](../guides/billing/manage-billing.md) and retry |
| `404` | `model_not_found` | Model ID is unknown, disabled, or outside your account/plan allowlist; verify via [List models](api/genesis/models.md) |
| `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:

- **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](../guides/matrixone/instances.md)).
- **Authentication or privilege denial**: Check `username:role_name` login formatting and tenant-scoped `GRANT` assignments ([Permissions: MatrixOne](../guides/matrixone/permissions.md) and [SQL privilege categories](sql/privileges.md)).
- **SQL syntax or import limits**: Consult [SQL limitations](sql/limitations.md) and [SQL Editor](../guides/ai-studio/processing/sql-editor.md).

## Related pages

- Symptom-based checklist across console, ingestion, compute, and sandboxes: [Troubleshooting and FAQ](../get-started/troubleshooting.md)
- Endpoint URLs, authentication headers, and workspace ID setup: [Prepare to call an API](api/common/index.md)
- Collecting diagnostics before opening a support ticket: [Support and feedback](../get-started/support.md)
