Skip to content

Core administration errors

Errors on /core/v1 use this envelope. message is safe English text; code and param are nullable. Clients act on the stable code and the optional param, show message for an unknown code, never parse messages and never retry a rejected write automatically.

json
{"error":{"message":"A valid Core key is required as the bearer credential.","type":"invalid_request_error","code":"invalid_admin_key","param":null}}

Errors on /v1 and /api/v1 keep their own envelopes and never carry details. The tables below list every code a /core/v1 or console caller can receive, except the wire vocabulary, such as invalid_request, not_found_error or idempotency_conflict, which keeps its /v1 meaning. Codes of /v1 Session input and of the machine routes, such as turn_conflict or invalid_node_credential, never reach these callers. The shared catalog services/core/internal/api/testdata/core-errors.json holds exactly the listed codes. A Go test requires a producer for each, an exact match with these tables and a catalog entry for every other code Core's error writers produce; Web's tests require a message for exactly these codes in each language.

Optional details ​

error.details, when present, is a nonempty flat object. Its values are strings, finite numbers, null or arrays of strings (possibly empty). It holds only Core-owned facts: never submitted names, URLs or keys, echoed request values, native error text or provider response bodies. Each code that has details lists its exact keys below.

CodeDetails
sandbox_generation_stalecurrent_generation
sandbox_in_useallocations, pending
sandbox_reset_requiredcurrent_provider, requested_provider
Operation validation codesSee operation validation

In the TypeScript client, AgentCoreError.details is the optional CoreErrorDetails. The Core clients accept only the value types above, copy string arrays, and ignore malformed or empty details without changing the error's message, status, code, param or type. The public OpenAIAgentsClient does not read details.

Console-generated failures ​

Web's console server uses this envelope for its own failures on /core paths (request boundary). It never exposes request values or transport exceptions, and it passes Core's responses through unchanged.

HTTP statusCodeMeaningtype
401console_sign_in_requiredThe console session is missing or expiredinvalid_request_error
403console_origin_rejectedHost, Origin or Fetch Metadata checks failedinvalid_request_error
400console_request_invalidThe path, method or upgrade is unsafeinvalid_request_error
502core_unreachableCore could not be reached, or Core answered with a redirectserver_error

These have null param and no details. A Core 401 invalid_admin_key therefore stays distinguishable from a missing console sign-in. Console sign-in routes keep their {"error":"…"} errors (sign-in).

Sandbox provider verification ​

A POST or PUT /core/v1/sandbox/deployment (sandbox deployment) whose provider verifies a credential or configuration, as E2B does, fails with these fixed errors. None returns provider text, a template name, a key or a resource count.

HTTPCodeMeaningparam
400sandbox_credential_invalidThe provider rejected the candidate credentialcredential
400sandbox_configuration_invalidThe candidate configuration, such as an E2B template build, is not ready and immutable or does not match the resourcesconfiguration
409sandbox_credential_ownershipThe candidate credential cannot manage the retained deployment; reset before changing accountscredential
503sandbox_verification_unconfirmedVerification, receipt settlement or the credential fence could not be confirmednull

On every deployment write, the typed client replaces the message of these codes and of the other sandbox_* deployment codes with fixed local text. It keeps only the current_generation, allocations, pending, min and max details, and keeps param only when status, code and param match the table or the invalid_sandbox_configuration rows below exactly. 409 sandbox_configuration_error becomes fixed public-URL guidance with a null param, even for a PUT without a key. Any other error becomes the client-only code sandbox_configuration_unconfirmed, which Core never returns, and is not resent, because a rejection could echo the key.

Operation validation ​

Each code returns HTTP 400 with type: "invalid_request_error". A missing, malformed or wrongly typed model-provider bundle returns invalid_model_provider before any field check. JSON body parsing keeps its own errors, and other malformed administration requests return invalid_request.

CodeParamDetailsMeaning
invalid_namenamemax_length: 128 for Projects and nodes, 80 for Project keysThe name failed the resource's validator
invalid_node_capacitymax_active or max_retainedmin: 1, max: 1000000Capacity is invalid; retained capacity must also be at least active capacity
invalid_model_providernullomittedA complete model-provider bundle is required
model_provider_base_url_invalidbase_urlomittedRequires HTTPS, or HTTP to a loopback or private IP address, without credentials, query or fragment
model_provider_protocol_unsupportedprotocolharness and allowed_protocols, from the build's adapter catalogThe protocol is unknown or unsupported by the selected Harness
model_provider_api_key_invalidapi_keymax_length: 16384The key is empty, too long or contains a prohibited character
model_provider_token_limits_invalidcontext_window or max_output_tokensomittedA limit is negative, max_output_tokens exceeds a set context_window, or the Harness has no native setting for a set limit
model_configuration_model_invalidmodelomittedThe deployment default's model is not a nonempty model identifier
harness_config_invalidharness_configomittedThe deployment default's native parameters are unsupported or invalid
invalid_sandbox_configurationresources.cpusmin: 1, max: 255The CPU count is outside the supported bounds
invalid_sandbox_configurationresources.memory_mibmin: 512, max: 1048576Memory is outside the supported bounds
invalid_sandbox_configurationresources.root_disk_mib or resources.environment_disk_mibmin: 1024 for microsandbox (environment_disk_mib also accepts 0); min: 0, max: 0 for E2B and OpenSandboxDisk capacity is missing or unsupported by the provider

Bounds are validation constants, never submitted values. Node names are limited in bytes; Project and key names in trimmed Unicode characters without control characters. Only the first failure is reported, in this order: model provider URL, protocol, key, limits, then the Harness's protocol; sandbox resources CPU, memory, then disk. Model-provider field errors inside a model_provider object keep that object's field as param. An unknown sandbox provider returns an error without these fields.

Other administration errors ​

These codes have null param and no details. Sandbox deployment describes when each sandbox code occurs.

HTTPCodeMeaning
400invalid_workspace_configurationInvalid workspace storage configuration
400workspace_operation_unsupportedThe selected workspace storage does not support the operation or sandbox combination
404workspace_storage_not_foundWorkspace storage is not configured or the requested object does not exist
409workspace_storage_conflictWorkspace storage ownership or configuration conflicts with the current state
409workspace_storage_requiredThe sandbox provider runs every Environment on workspace storage and none is selected
503workspace_storage_unavailableWorkspace storage is unavailable or an operation remains unconfirmed
400sandbox_operation_unsupportedThe selected sandbox provider does not support the operation
401invalid_admin_keyThe bearer credential is not a valid Core key
404not_foundThe operation does not exist, the Harness is unknown, or the Harness has no deployment default model provider
409project_archivedThe target Project is archived
409project_existsThe Project ID already exists
409project_api_key_existsThe API key ID already exists
409executor_credential_existsThe executor credential ID already exists; rotate it to replace the secret
409sandbox_not_configuredThe sandbox deployment is not configured
409 or 503sandbox_reset_in_progressA sandbox reset is in progress
409sandbox_configuration_errorThe installation cannot serve the selected provider, such as E2B while the public URL is loopback
409sandbox_deployment_conflictThe sandbox deployment cannot change in its current state
409sandbox_specification_mismatchThe saved deployment specification is no longer valid for its provider
409runtime_node_in_useThe node still holds allocations, snapshots, reservations or pending cleanup
409environment_unavailableThe Session's environment is no longer available, such as a hosted environment that failed to provision
409runtime_history_unsupportedRuntime history is not supported for the Session
500internal_errorCore could not complete the operation
503runtime_node_unavailableNo sandbox node is available or has capacity
503execution_unavailableExecution is not available, such as while Core shuts down
503runtime_history_unavailableDurable Runtime history is temporarily unavailable
503core_metrics_unavailableCore metrics could not be read
503file_transfer_unavailableBounded content transfer is unavailable

Diagnostic failure categories ​

The Session diagnostics routes return these categories inside a successful 200 snapshot, not as an error envelope. A public /v1 Turn error reports some of them under official codes, as Differences from OpenAI describes. params is {} unless the table says otherwise.

CodeStored cause or safe meaning
harness_errorengine_failed without a native classification
authentication_errorNative provider authentication rejected
rate_limit_exceededNative rate limit classification
usage_limit_exceededNative billing or usage limit classification
server_overloadedNative overload classification
server_errorNative server failure classification
invalid_requestNative request rejection
resource_not_foundNative resource/model not found
request_timeoutNative provider timeout classification
context_length_exceededNative context limit classification
cyber_policyNative cyber policy rejection
connection_failedNative connection failure; params contain http_status, an integer in 100–599 or null
model_provider_requiredMissing frozen model provider
runtime_unavailableexecution_device_unavailable, execution_unavailable
runtime_disconnecteddevice_disconnected, event_stream_incomplete
runtime_preparation_failedpreparation_start_failed, preparation_interrupted
execution_interruptedCore execution interrupted
delivery_unconfirmeddelivery_unknown, input_outcome_unknown, cancel_unconfirmed, cancel_outcome_unavailable, function_result_unconfirmed
input_rejectedinvalid_input, input_not_applied, message_input_unsupported, and the exact steering outcomes input_invalid_input, input_run_inactive, input_input_conflict, input_input_limit, input_unsupported, input_rejected, input_not_ready, input_busy
executor_protocol_errorinvalid_executor_result, execution_state_unavailable, execution_state_changed, function_call_invalid, function_result_invalid
core_storage_failedevent_persistence_failed, artifact_capture_failed
internal_errorUnknown or malformed outcome; no raw value is returned
environment_connection_timeoutInitial input connection deadline expired
environment_unavailableEnvironment unavailable for initial input
environment_provisioning_failedHosted provisioning failure; params contain nullable step, index, exit_code from a sanitized receipt, and category for a failure without a confirmed step

A database failure is an error, never an empty or healthy snapshot. Provisioning reasons and native messages are never parsed for categories or parameters.

Native categories apply only to a failed Turn whose outcome has error_code: engine_failed. Core accepts only the listed engine_error_code values; an unknown, malformed or absent value stays harness_error. Only connection_failed uses engine_http_status. Nested metadata and provider text never classify a failure. Core storage, incomplete-stream and cancellation failures take precedence, and cancelled or completed Turns have no failure. Native error classification lists which adapters report each category.

Released under the MIT License. © 2026 MiniMax-AI