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
| Enum | Values | Used by |
|---|---|---|
RuntimeStatus | 10 values above | RuntimeResult.status, settled usage.status, messages.error_code |
UsageStatus | RuntimeStatus plus reserved, rejected_budget, rejected_disabled | usage.status (CHECK usage_status_valid) |
ErrorCode | 17 values: the 8 runtime failure codes plus the HTTP-only unauthorized, rate_limited, busy, payload_too_large, not_found, unavailable, conflict, forbidden, too_many_pending | ApiError.error.code, SSE error events, SessionView.messages[].errorCode |
FactoryErrorCode | max_iterations, budget_exhausted, approval_rejected, approval_expired, agent_failed, pr_closed_by_human, repo_too_large, internal_error, disabled | factory_jobs.error_code (only when status = 'failed') |
| Quality error codes | free text matching ^[a-z][a-z0-9_]{0,63}$, for example exec_lost | quality_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.
| HTTP | ErrorCode |
|---|---|
| 400 | invalid_request, unsupported_capability |
| 401 | unauthorized |
| 403 | forbidden |
| 404 | not_found |
| 409 | conflict |
| 413 | payload_too_large |
| 429 | rate_limited, busy, budget_exhausted, too_many_pending |
| 500 | internal_error |
| 502 | agent_failed, agent_limit |
| 503 | disabled, unavailable |
| 504 | timeout |
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' }.
| Input | Cause | HTTP | Code in body | Retry-After (s) |
|---|---|---|---|---|
success | any | 200 | none | none |
agent_limit, timeout, agent_failed, disabled, budget_exhausted, internal_error | any | Table E | same code | none |
invalid_request, unsupported_capability (from the runtime) | any | 500 | internal_error | none |
aborted | shutdown | 503 | unavailable | 5 |
aborted | client_closed | no reply (kind: 'none', the API answers 204 with no body) | ||
aborted | other | 500 | internal_error | none |
unavailable | shutdown | 503 | unavailable | 5 |
unavailable | temporal_unreachable | 503 | unavailable | 30 |
unavailable | other | 503 | unavailable | none |
busy | any | 429 | busy | 5 |
rate_limited | window | 429 | rate_limited | seconds to the end of the current UTC minute: ceil((60000 - now % 60000) / 1000) (WINDOW_MS = 60_000) |
rate_limited | other | 429 | rate_limited | none |
unauthorized, forbidden, not_found, conflict, payload_too_large, too_many_pending | any | Table E | same code | none |
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) setsRetry-AfterwhenretryAfterSecis present;x-request-idis set by the request-id middleware.- The message is the caller-supplied message or, by default, the code with underscores replaced by spaces.
internal_erroralways carries the generic messageinternal error; details are only logged. POST /v1/agent/streamends with exactly one SSEdoneorerrorevent; anerrorevent'sdatais{ code, message, requestId }with the sameErrorCodeset.@agentforge/agent-clientraisesAgentApiErrorfor a non-2xx body that is anApiErrorand exposes the parsedRetry-AfterasretryAfterSec(digits only). It never retries by itself.
Mapping stored codes
Codes stored in Postgres are raw; the API maps them on read.
| Stored in | Mapping on read |
|---|---|
messages.error_code | Unknown 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_code | A 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_code | Returned 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
| Activity | Timeouts | Retry policy |
|---|---|---|
failTurn, closeSession, finishTurn | start-to-close 30 s | initial 5 s, coefficient 2, max interval 5 min, no attempt limit (they only write Postgres and must eventually run) |
prepareTurn | start-to-close 30 s | initial turnRetryInitialIntervalMs (default DEFAULT_TURN_RETRY_INITIAL_INTERVAL_MS = 5000), coefficient 2, maximumAttempts = MAX_TURN_ATTEMPTS + 1 = 4 |
executeTurn | start-to-close 360 s, heartbeat timeout from the API, schedule-to-start on the fleet queue DEFAULT_EXEC_SCHEDULE_TO_START_MS = 60_000 | maximumAttempts: 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 s | same as prepareTurn |
Activity failure codes thrown by the session activities:
| Code | Retryable | Thrown when |
|---|---|---|
db_error | yes | Postgres unavailable in an activity |
gateway_unavailable (GATEWAY_UNAVAILABLE) | yes | job registration at the gateway control port failed |
turn_interrupted | yes | worker shutdown cancelled the turn (retried, never aborted) |
invalid_workflow_args | no | workflow input failed validation (before any activity runs) |
workflow_error | no | any 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 type | Statuses seen in apps/gateway/src |
|---|---|
invalid_request_error | 400, 405, 408, 409 |
authentication_error | 401 |
permission_error | 403 |
not_found_error | 404 |
rate_limit_error | 429 |
overloaded_error | 503 (control: busy) |
api_error | 500, 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.tspackages/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(ApplicationFailurecodes)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.tspackages/db/src/schema.ts(factory_jobs_error_code_valid,quality_runs_error_code_valid)