Skip to main content

Error model

AgentForge has one status vocabulary. Every non-success runtime status is also an ErrorCode, so there is no mapping table between runtime and API codes. The HTTP layer adds a few codes that never reach the ledger. Two pure functions in packages/agent-types/src/http.ts turn codes into HTTP replies: HTTP_STATUS (Table E, code to status) and toResponse (Table S, status plus cause to the full reply including Retry-After).

The vocabularies​

EnumValuesUsed by
RuntimeStatus10 values aboveRuntimeResult.status, settled usage.status, messages.error_code
UsageStatusRuntimeStatus plus reserved, rejected_budget, rejected_disabledusage.status (CHECK usage_status_valid)
ErrorCode17 values: the 8 runtime failure codes plus the HTTP-only unauthorized, rate_limited, busy, payload_too_large, not_found, unavailable, conflict, forbidden, too_many_pendingApiError.error.code, SSE error events, SessionView.messages[].errorCode
FactoryErrorCodemax_iterations, budget_exhausted, approval_rejected, approval_expired, agent_failed, pr_closed_by_human, repo_too_large, internal_error, disabledfactory_jobs.error_code (only when status = 'failed')
Quality error codesfree text matching ^[a-z][a-z0-9_]{0,63}$, for example exec_lostquality_runs.error_code (only when status = 'error')

aborted is a RuntimeStatus but not an ErrorCode: it never appears in an API body. forbidden was added in P3-5 for authenticated clients outside FACTORY_CLIENTS / FACTORY_APPROVERS; too_many_pending for CodeCrucible's QUALITY_MAX_PENDING_PER_CLIENT.

Table E: ErrorCode to HTTP status​

HTTP_STATUS is typed satisfies Record<ErrorCode, number>, so adding a code without a status is a compile error.

HTTPErrorCode
400invalid_request, unsupported_capability
401unauthorized
403forbidden
404not_found
409conflict
413payload_too_large
429rate_limited, busy, budget_exhausted, too_many_pending
500internal_error
502agent_failed, agent_limit
503disabled, unavailable
504timeout

Table S: toResponse(input, cause, now)​

toResponse is "the only status/cause to response mapping". input is a RuntimeStatus or an ErrorCode; cause is one of none, client_closed, shutdown, temporal_unreachable, window. It returns { kind: 'reply', http, code?, retryAfterSec? } or { kind: 'none' }.

InputCauseHTTPCode in bodyRetry-After (s)
successany200nonenone
agent_limit, timeout, agent_failed, disabled, budget_exhausted, internal_erroranyTable Esame codenone
invalid_request, unsupported_capability (from the runtime)any500internal_errornone
abortedshutdown503unavailable5
abortedclient_closedno reply (kind: 'none', the API answers 204 with no body)
abortedother500internal_errornone
unavailableshutdown503unavailable5
unavailabletemporal_unreachable503unavailable30
unavailableother503unavailablenone
busyany429busy5
rate_limitedwindow429rate_limitedseconds to the end of the current UTC minute: ceil((60000 - now % 60000) / 1000) (WINDOW_MS = 60_000)
rate_limitedother429rate_limitednone
unauthorized, forbidden, not_found, conflict, payload_too_large, too_many_pendinganyTable Esame codenone

A runtime invalid_request is a server fault because the HTTP layer already validated the input; the HTTP layer's own 400 (invalidRequest in apps/api/src/errors.ts) never goes through toResponse.

Response shapes​

The API answers every error with ApiError (strict):

{ "error": { "code": "budget_exhausted", "message": "budget exhausted" }, "requestId": "..." }
  • sendOutcome (apps/api/src/errors.ts) sets Retry-After when retryAfterSec is present; x-request-id is set by the request-id middleware.
  • The message is the caller-supplied message or, by default, the code with underscores replaced by spaces. internal_error always carries the generic message internal error; details are only logged.
  • POST /v1/agent/stream ends with exactly one SSE done or error event; an error event's data is { code, message, requestId } with the same ErrorCode set.
  • @agentforge/agent-client raises AgentApiError for a non-2xx body that is an ApiError and exposes the parsed Retry-After as retryAfterSec (digits only). It never retries by itself.

Mapping stored codes​

Codes stored in Postgres are raw; the API maps them on read.

Stored inMapping on read
messages.error_codeUnknown code: internal_error. Known code: toResponse(code, 'none', now).code. So a refused workspace stored as invalid_request reads as internal_error
factory_jobs.error_codeA value that is also an ErrorCode is mapped as above; factory-only codes such as max_iterations or approval_expired are returned as stored (FactoryJobView.errorCode is a plain string)
quality_runs.error_codeReturned as stored

Retry semantics​

HTTP callers decide retries themselves using Retry-After. Inside the platform, Temporal activity retry policies and the ledger fences decide.

Session turns​

ActivityTimeoutsRetry policy
failTurn, closeSession, finishTurnstart-to-close 30 sinitial 5 s, coefficient 2, max interval 5 min, no attempt limit (they only write Postgres and must eventually run)
prepareTurnstart-to-close 30 sinitial turnRetryInitialIntervalMs (default DEFAULT_TURN_RETRY_INITIAL_INTERVAL_MS = 5000), coefficient 2, maximumAttempts = MAX_TURN_ATTEMPTS + 1 = 4
executeTurnstart-to-close 360 s, heartbeat timeout from the API, schedule-to-start on the fleet queue DEFAULT_EXEC_SCHEDULE_TO_START_MS = 60_000maximumAttempts: 1; the workflow loop retries through a new prepareTurn (new requestId#n and job token)
runTurn (histories before the fleet-split patch)start-to-close 360 ssame as prepareTurn

Activity failure codes thrown by the session activities:

CodeRetryableThrown when
db_erroryesPostgres unavailable in an activity
gateway_unavailable (GATEWAY_UNAVAILABLE)yesjob registration at the gateway control port failed
turn_interruptedyesworker shutdown cancelled the turn (retried, never aborted)
invalid_workflow_argsnoworkflow input failed validation (before any activity runs)
workflow_errornoany non-Temporal error escaping the workflow, so the workflow fails instead of retrying its task forever

Factory steps​

factoryJobWorkflow uses maximumAttempts = MAX_STEP_ATTEMPTS + 1 = 4 (initial DEFAULT_STEP_RETRY_INITIAL_INTERVAL_MS = 5000, coefficient 2) for role and test steps, and 5 attempts with a 10 minute start-to-close timeout for git activities. The database bounds attempts too (factory_steps.attempts BETWEEN 0 AND 3). Retryable activity codes: db_error, repo_not_configured, step_interrupted, test_runner_error. See Job lifecycle.

Quality runs​

Exec activities use maximumAttempts: 1 (a retry would land on the same worker identity); a lost exec worker is handled by preparing the workspace again, up to maxReprepares = 2, then the run ends error with exec_lost. Admission busy waits min(1000 * 2^n, MAX_ADMIT_RETRY_MS = 60_000) ms and continues-as-new after 60 history events (ADMIT_HISTORY_LIMIT). Non-retryable codes include invalid_args, workspace_missing, not_enabled, chunk_mismatch, run_closed, invalid_children, invalid_workflow_args, workflow_error. See Assessment workflow.

Gateway errors​

The gateway speaks the provider's error shape, not ApiError:

{ "type": "error", "error": { "type": "permission_error", "message": "model not allowed" } }
Error typeStatuses seen in apps/gateway/src
invalid_request_error400, 405, 408, 409
authentication_error401
permission_error403
not_found_error404
rate_limit_error429
overloaded_error503 (control: busy)
api_error500, 502, 503 (shutting down, disabled, ledger unavailable)

Each data-port denial is also written to gateway_audit with a reason from AuditReason (for example model_not_allowed, max_tokens_invalid, budget_exhausted, registration_stale, disabled). The full list is on Gateway.

Sources​

  • packages/agent-types/src/index.ts (ErrorCode, RuntimeStatus, UsageStatus)
  • packages/agent-types/src/http.ts (ApiError, StreamEvent, HTTP_STATUS, ResponseCause, HttpOutcome, WINDOW_MS, toResponse)
  • packages/agent-types/src/factory.ts (FactoryErrorCode, FactoryJobView), packages/agent-types/src/audit.ts (AuditReason)
  • apps/api/src/errors.ts (sendOutcome, errorMessage, invalidRequest), apps/api/src/sessions.ts (mapCode), apps/api/src/factory.ts (mapCode), apps/api/src/quality.ts
  • packages/agent-client/src/index.ts (AgentApiError)
  • packages/agent-workflows/src/workflows/index.ts, shared.ts, factory.ts, factory-shared.ts, quality.ts (ADMIT_HISTORY_LIMIT, MAX_ADMIT_RETRY_MS), quality-shared.ts (QUALITY_RUN_LIMITS)
  • apps/worker/src/activities.ts, apps/worker/src/exec-activities.ts, apps/worker/src/factory/activities.ts, apps/worker/src/quality/exec-activities.ts, apps/worker/src/quality/core-activities.ts (ApplicationFailure codes)
  • packages/agent-runtime-claude/src/runtime.ts (GATEWAY_UNAVAILABLE)
  • apps/gateway/src/errors.ts (errorJson, errorResponse), apps/gateway/src/proxy.ts, apps/gateway/src/control.ts, apps/gateway/src/mcp/route.ts
  • packages/db/src/schema.ts (factory_jobs_error_code_valid, quality_runs_error_code_valid)