Errors - Evolve

A refused request raises one class. Branch on its code, never on the message.

TypeScript
Python

import { EvolveApiError, HOSTED_ERROR_CODES, isHostedErrorCode } from "@evolvingmachines/evolve";

class EvolveApiError extends Error {
  status: number;                 // the HTTP status
  code: HostedErrorCode | string; // the stable code below; "unknown_error" when the server sent none, or one a newer server added
  message: string;                // the server's sentence; may be shortened when a list is long
  param?: string;                 // the input the refusal is about: a body path, a query parameter, or a multipart part
  details?: Record<string, unknown>; // the complete machine-readable data; never shortened
  retryAfterSec?: number;         // on 429 and 503, from the body first, the Retry-After header second
  requestId?: string;             // the server's id for this failure, from x-request-id; quote it in support
  isKnownCode(): boolean;
}

try {
  await jobs().start({ datasets: [{ name: "terminal-bench-4" }], agents: [{ name: "codex", model_name: "gpt-6-astra" }], sandbox_provider: "modal" });
} catch (err) {
  if (err instanceof EvolveApiError && err.code === "provider_unsupported") {
    const { refused_tasks } = err.details as { refused_tasks: { task_name: string; reason: string }[] };
  }
}

HOSTED_ERROR_CODES is the closed list as a runtime array and isHostedErrorCode(value) narrows a string to it. The same list is published as error_codes in the capability document.

from evolve import EvolveAPIError, HOSTED_ERROR_CODES, is_hosted_error_code

class EvolveAPIError(Exception):
    status: int                        # the HTTP status
    code: str                          # the stable code below; "unknown_error" when the server sent none
    param: Optional[str]               # the input the refusal is about
    details: Optional[Dict[str, Any]]  # the complete machine-readable data; never shortened
    retry_after_sec: Optional[float]   # on 429 and 503
    request_id: Optional[str]          # the server's id for this failure; quote it in support
    def is_known_code(self) -> bool: ...

try:
    await jobs().start(datasets=[{"name": "terminal-bench-4"}], agents=[{"name": "codex", "model_name": "gpt-6-astra"}], sandbox_provider="modal")
except EvolveAPIError as err:
    if err.code == "provider_unsupported":
        refused = (err.details or {}).get("refused_tasks", [])

str(err) is the server’s sentence, which may be shortened when a list is long. HOSTED_ERROR_CODES is the closed list and is_hosted_error_code(value) tests a string against it.

Every response, success or failure, carries the same id in its x-request-id header. Of the 429 codes only rate_limited carries a retry delay; quota_exceeded and every too_many_concurrent_* code carry none.

Errors that are not API refusals

These mean the request succeeded, or never happened, and something else went wrong. They are separate classes, not codes.

NoActiveVersionError: datasets().getActive() (Python get_active) on a dataset with no active version. Carries dataset.
ImportSettleError: watchImport() (Python watch_import) reached its settle timeout before the version settled. code is settle_timeout; carries importId (Python import_id), dataset, version and the last observed state. When state is FAILED the version did settle; read the failure with getImport() (Python get_import).
EvolveDigestMismatchError: a download’s bytes do not match the digest the server stated. Carries expected and actual. Do not trust the stored object.
EvolveIncompleteDownloadError: fewer bytes arrived than Content-Length promised. Carries expectedBytes and receivedBytes (Python expected_bytes, received_bytes). Retry the download.
EvolveUploadTimeoutError, TypeScript only: an upload saw no socket activity for 600 seconds. Retry the upload.

The codes

Grouped by the door that returns them. The HTTP status is stated where it is fixed.

Keys and limits

Code	When
`missing_authorization`	No API key on the request.
`invalid_api_key`	The key is not valid.
`read_only_key`	403. A read-only key on a mutating route.
`credential_service_unavailable`	The key could not be checked; retry.
`rate_limited`	429. Wait `retryAfterSec`; every SDK watch loop does so on its own.
`insufficient_credits`	402. The account’s credit balance is zero at job create, resume or retry.
`quota_exceeded`	429, no retry delay. The organization’s `max_queued_trials` would be crossed. `details` carry `quota`, `limit`, `used`, `requested` and `org`. The CLI prints `Launch quota exceeded:` and exits 2.

Input

Code	When
`invalid_json`	The body is not JSON.
`invalid_input`	A field is malformed; the message names it and `param` names it when the server can. Also the 413 for a trial home too large to serve as one text view (`details`: `size_bytes`, `max_unranged_bytes`).
`invalid_limit`, `invalid_cursor`, `invalid_after`	A paging parameter is malformed.
`invalid_status`, `invalid_visibility`, `invalid_format`	A filter or selector names a value outside its closed set.
`invalid_ids`	400. A stop batch that is empty or over 100 ids.
`invalid_multipart`	400. An upload that is not `multipart/form-data`, or is malformed.
`idempotency_key_reused`	409. The key already stands for a different request.
`concurrent_update`	The row changed under the request; read it again.

Datasets and publishing

Code	When
`dataset_not_found`	The name does not exist, or belongs to someone else; the two are never told apart.
`dataset_version_not_found`	The version does not exist.
`dataset_name_taken`	409. The name belongs to another publisher.
`dataset_in_use`	409. Jobs reference the dataset; `details` name them.
`dataset_not_owned`	The caller does not own it; a platform dataset has no owner.
`dataset_import_in_progress`	409. A visibility change while a version is importing; `details` name the version.
`upstream_not_watchable`	Auto-import on a dataset with no moving git ref.
`no_active_version`	A bare name on a dataset with no active version.
`version_not_ready`	409. A job or an activation on a version that is not READY.
`version_not_activatable`	A FAILED or ARCHIVED version.
`unknown_task_names`, `no_tasks`	A selector names tasks the version lacks, or filters every task away.
`task_not_found`	404. `getTaskBuild()` on a name with no recorded outcome.
`task_failed_to_build`	A job create that names a task whose build FAILED; `details.failed_tasks` quote each reason.
`unpinned_git_ref`	A git publish on a branch; `details.commit` is the sha to pin.
`hub_package_not_found`	400. The hub package does not exist or is private; `details.hub_package`.
`hub_unreachable`	502. The hub could not be asked; retry the publish.
`invalid_archive`	The tarball is unreadable or unsafe.
`import_too_large`	413. A dataset archive over the published ceiling.
`import_not_found`	The import id does not exist or is not yours.
`too_many_concurrent_imports`	429, no retry delay. Too many uploads in flight; retry when one finishes. `details.max_concurrent`.
`package_not_retained`, `package_corrupt`, `package_missing`	409. The original package was never retained, is corrupt, or is gone. Re-publish.
`too_many_concurrent_package_downloads`	429, no retry delay. `details.max_concurrent`.
`upload_session_not_found`, `upload_offset_mismatch`, `upload_chunk_digest_mismatch`, `upload_incomplete`, `upload_archive_digest_mismatch`, `upload_session_failed`, `too_many_concurrent_upload_chunks`	A large upload’s session failed; the SDK surfaces the refusal as is. Retry the publish or upload.

Jobs, trials, regrades

Code	When
`provider_unsupported`	422. A selected task is refused on the chosen provider; `details.refused_tasks` carry each reason. A GPU task that moves to `modal` is not refused; the trial records the move as `sandbox_provider_degrade`.
`job_not_found`	The job does not exist or is not visible to you. A regrade job id on delete.
`job_not_terminal`	409. Resume, retry, regrade, analyze or delete on a live job; on delete also a live regrade, listed in `details.regrade_job_ids`.
`no_failed_trials`	409. Resume, or retry with `failed_only`, found nothing.
`trial_not_found`	404. A retry names a trial the job does not own; a trace feed id no run owns.
`trial_not_settled`	409. A retry names a trial still running.
`regrade_source_ineligible`	409. The trial recorded no verifier inputs; the message says why.
`no_regradable_trials`	409. A whole-job regrade found nothing eligible.
`org_forbidden`	403. A member who did not create the job tried to delete it.
`job_uploaded`	409. Resume, retry or regrade on an uploaded job.
`secret_not_found`, `secret_ambiguous`, `secret_brokered_unsupported`, `secret_exists`, `secret_not_attached`	See secrets.
`agent_version_not_found`	A version pin that does not resolve.
`agent_version_unresolvable`	502. The latest version could not be looked up; retry the create.
`agent_kwarg_unsupported`, `agent_config_unsupported`, `agent_config_key_refused`, `agent_preset_unsupported`	See agents.

Analyze and check

Code	When
`invalid_rubric`	400. Unknown keys, empty or duplicate criteria, or a length bound exceeded.
`analysis_already_running`	409. One analysis wave at a time; also blocks delete.
`no_analyzable_trials`	409. Every trial is CANCELLED, or the filter selects nothing.
`analysis_not_found`	404. An analysis you cannot read or that never existed.
`analysis_not_terminal`	409. Download of an analysis still queued or running.
`check_not_found`	404. Neither a check nor a task check you can read.
`check_not_terminal`	409. Download of a check or task check not yet settled.
`no_checkable_tasks`	400. No task directory in the archive, or the globs and the cap left nothing.
`too_many_concurrent_check_uploads`	429, no retry delay. `details.max_concurrent`.

Job upload

The upload door itself answers four codes: invalid_multipart (400), invalid_input (400), upload_too_large (413) and too_many_concurrent_job_uploads (429). Everything else arrives on the import’s failure, with no HTTP status.

Code	When
`not_a_job_dir`	No `result.json` and `config.json` at the root, or they do not parse.
`invalid_archive`	The tarball is unreadable or unsafe.
`invalid_trial`	One trial’s `result.json` cannot be ingested; the failure names the trial.
`trial_too_large`	Not a failure: the trial is skipped and listed on `skipped_trials`; `details` carry `file`, `bytes`, `max_bytes`.
`upload_too_large`	The archive is over the published ceiling, at the door or when extracted.
`job_already_uploaded`	You already uploaded this archive’s job; `details.existing_job_id`. Delete it to replace it.
`too_many_concurrent_job_uploads`	429, no retry delay. `details.max_concurrent`.
`job_import_not_found`	404. An import that is not yours or does not exist.

Registered agents and skills

Code	When
`agent_not_found`	Another owner’s name reads the same as none.
`agent_name_taken`, `agent_name_reserved`, `agent_invalid_name`	The name is used, collides with a built-in, or breaks the published pattern.
`agent_source_required`, `agent_source_conflict`	Neither an install script nor a directory, or both.
`agent_invalid_env`	The declared env overrides a run-contract key, or looks like a credential.
`agent_too_large`, `agent_limit_reached`	The tarball or the per-user count is over the published limit.
`skill_not_found`, `skill_name_not_found`	An `upload:<id>` or a `name:<skill-name>` that does not resolve.
`skill_ref_invalid`, `skill_unresolvable`, `skill_invalid`	A reference that does not parse, cannot be fetched, or holds no valid skill.
`skill_in_use`	409. A running job references the upload.
`skill_too_large`, `skill_limit_reached`	The tarball or the per-user count is over the published limit.
`too_many_concurrent_skill_uploads`	429, no retry delay. `details.max_concurrent`.

Organizations

org_not_found, org_slug_taken, org_forbidden, org_personal_immutable, org_last_owner, org_in_use, org_member_not_found, invite_not_found and invite_invalid belong to team accounts. The SDK reads organizations only, so only org_not_found and org_forbidden can reach it today. internal_error is the server’s own failure; quote requestId.

​Errors that are not API refusals

​The codes

​Keys and limits

​Input

​Datasets and publishing

​Jobs, trials, regrades

​Analyze and check

​Job upload

​Registered agents and skills

​Organizations