/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.
/v1 and /api/v1 keep their own envelopes and never carry details.
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.
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.
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
APOST 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.
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 sandbox_configuration_unconfirmed and is not resent, because a rejection could echo the key.
Operation validation
Each code returns HTTP 400 withtype: "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.
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, general limits, the Harness’s protocol, then the Harness’s required limits; sandbox resources CPU, memory, disk, then Runtime. 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.
Diagnostic failure categories
The Session and Turn diagnostics reads return these categories inside a successful 200 snapshot, not as an error envelope. Public/v1 Turn errors do not change. params is {} unless the table says otherwise.
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.