API error codes

The orchestrator’s HTTP endpoints return an error field on any failed request. The tables below list the errors each endpoint can return, grouped by who calls it: integration and callback endpoints used by runners and automation, and the admin API behind the admin UI.

Run statuses and failures

What AI-Implement reports about a run — statuses, ticket comments, and failure messages.

Troubleshooting

Step-by-step fixes for the most common problems.

Response body shapes

A failed request returns a JSON body with a single error field:

string

The error identifier that varies by endpoint.

For /runner/* and /trigger/gap-fill, a stable slug code (for example, missing_bearer).
For /api/* and the webhook, a human-readable message (for example, Invalid JSON body).

Some responses add fields alongside error, noted per endpoint below.

Integration and callback API

These endpoints are called by runners (GitHub Actions jobs, Fly Machine sessions, or local Docker containers) and by external automation, not from the admin UI. They do not use the admin session — each authenticates with a token or nonce tied to the run or trigger.

`POST /runner/result`

A runner reports the final outcome of a dispatch: success with a PR, or failure with error context.

HTTP	`error`	Condition
400	`invalid_body`	Body is missing or not a JSON object
400	`invalid_comment_shape`	A comment entry is not an object with a string `body`
400	`invalid_comments`	`comments` is missing or not an array
400	`invalid_outcome`	`outcome` is not `success` or `failure`
400	`invalid_phase`	`phase` is not `planning`, `implementation`, or `gap-analysis`
400	`missing_prUrl`	A successful implementation result did not include a PR URL
400	`phase_mismatch`	The token’s phase does not match the body
401	`bad_signature`, `expired`, `malformed`, `wrong_audience`	The run token has a bad signature, is expired, is malformed, or is for the wrong endpoint
401	`missing_bearer`	Missing or malformed `Authorization: Bearer` header
409	`already_consumed`	The single-use token was already consumed

`POST /runner/progress`

A runner streams step-by-step progress during a run.

HTTP	`error`	Condition
400	`invalid_body`	Body is missing or not a JSON object
400	`invalid_step_id`	`step.id` is missing or not a string
400	`invalid_step_started_at`	`step.started_at` is missing or not a string
400	`invalid_step_status`	`step.status` is missing or not a string
400	`invalid_step_type`	`step.type` is missing or not a string
400	`step_required`	`step` is missing or not an object
401	`bad_signature`, `expired`, `malformed`, `wrong_audience`	The progress token has a bad signature, is expired, is malformed, or is for the wrong endpoint
401	`missing_bearer`	Missing or malformed `Authorization: Bearer` header
404	`job_not_found`	No run matches the token

`GET /runner/planning-context`

A runner fetches the planning context for its run.

HTTP	`error`	Condition
401	`bad_signature`, `expired`, `malformed`, `wrong_audience`	The progress token has a bad signature, is expired, is malformed, or is for the wrong endpoint
401	`missing_bearer`	Missing or malformed `Authorization: Bearer` header

`POST /trigger/gap-fill`

External automation triggers a gap-fill run on an existing pull request.

HTTP	`error`	Condition
400	`issueKey and positive integer prNumber required`	`issueKey` is missing, or `prNumber` is not a positive integer
401	`unauthorized`	Missing bearer token, or it does not match the trigger secret
404	`mapping_not_found`	No configured mapping owns an issue with this key
423	`project_paused`	The owning mapping is paused (response also includes `teamKey`)
501	`Gap fill trigger not configured`	The gap-fill trigger is not configured on this orchestrator
502	`dispatch_failed`	The workflow dispatch to GitHub failed (response also includes `detail` and `dispatchStatus`)

`POST /api/token`

A session requests a short-lived GitHub token, issued against a one-time nonce.

HTTP	`error`	Condition
400	`nonce and owner are required`	`nonce` or `owner` is missing
403	`Invalid or expired nonce`	No active job matches the nonce
403	`Owner mismatch`	The `owner` does not match the job’s repository owner
500	`Failed to generate token`	The body was not valid JSON, or token generation failed

`POST /api/status`

A session posts a lifecycle status event, which becomes a comment on the issue.

HTTP	`error`	Condition
400	`event is required`	`event` is missing or not a string
400	`Invalid JSON body`	Body could not be parsed as JSON
400	`nonce is required`	`nonce` is missing or not a string
400	`Unknown event type: {type}`	`event` is not an allowed remote event type
403	`Invalid or expired nonce`	No active job matches the nonce
500	`Internal server error`	An unexpected error occurred (for example, posting the status comment failed)

`POST /api/step-report`

A runner reports the status of a single pipeline step.

HTTP	`error`	Condition
400	`nonce is required`	`nonce` is missing or not a string
400	`Invalid JSON body`	Body could not be parsed as JSON
400	`step is required`	`step` is missing or not an object
400	`step.id is required and must be a string`	A required step field (`id`, `type`, `status`, `started_at`) is missing or not a string
403	`Invalid or expired nonce`	No active job matches the nonce
500	`Internal server error`	An unexpected error occurred while persisting the step

`POST /api/github/webhook`

GitHub notifies the orchestrator of pull-request events.

Events that don’t match a merged pull request return 200 and are ignored.

HTTP	`error`	Condition
400	`Invalid JSON payload`	Body could not be parsed as JSON
400	`Missing required PR fields`	The merged-PR payload is missing a required field (number, URL, branch, merge-commit SHA, or repository)
401	`Invalid signature`	The `X-Hub-Signature-256` did not verify against the webhook secret

Admin API

These endpoints support the admin UI. See Admin UI for what each panel does.

Some sections below cover several related endpoints that return the same errors.

Every admin endpoint below requires a valid admin session except POST /api/auth.Requests without one return 401 with Unauthorized.

`POST /api/auth`

Exchange the admin access code for a session token.

HTTP	`error`	Condition
400	`Invalid request body`	Body could not be parsed as JSON
403	`Invalid access code`	The access code does not match

Job steps and issue lists

GET /api/jobs/{jobId}/steps returns a job’s step history
GET /api/issues lists tracked issues
GET /api/blockers lists issues currently blocked from dispatch

HTTP	`error`	Condition
404	`job not found`	No job with that ID
502	(underlying error message)	Fetching issues from the ticketing provider failed

Responses shown as (underlying error message) return the raw error text with a 500 or 502 status, not a stable code. Treat them as diagnostic detail — the wording can change between releases.

`POST /api/mappings`

Create or update a project mapping.

Every field validation returns 400 with a message naming the problem.

Required fields

HTTP	`error`	Condition
400	`defaultBranch is required`	No default branch was given, and the mapping has none set
400	`Invalid request body`	Body could not be parsed as JSON
400	`teamKey, owner, and repo are required`	One of these required fields is missing

Claude provider

HTTP	`error`	Condition
400	`awsRegion is required when provider is 'bedrock'`	`provider` is `bedrock` but no AWS region was given
400	`provider 'bedrock' is not supported with executionMode 'fly-machines'`	`bedrock` was combined with `fly-machines`
400	`provider must be 'anthropic' or 'bedrock'`	`provider` is some other value

Execution and resources

HTTP	`error`	Condition
400	`executionMode must be 'github-actions' or 'fly-machines'`	`executionMode` is some other value
400	`machineCpus must be a positive integer`	`machineCpus` is below 1 or not an integer
400	`machineMemoryMb must be an integer >= 256`	`machineMemoryMb` is below 256 or not an integer
400	`sessionMode must be 'autonomous', 'interactive', or 'hybrid'`	`sessionMode` is some other value

Other settings

HTTP	`error`	Condition
400	`branchPrefix invalid: {detail}`	The branch prefix is invalid
400	`extraEnv must be a plain object`	`extraEnv` is set but is not an object
400	`extraEnv values must all be strings`	An `extraEnv` value is not a string
400	`maxInProgressAiIssues must be a positive integer`	`maxInProgressAiIssues` is below 1 or not an integer
400	`planningWorkflowFile is required when planningEnabled is true`	Planning is enabled but no planning workflow file was given
400	(ticketing validation message)	The ticketing provider configuration is invalid

Mapping changes

PATCH /api/mappings/{teamKey} updates a mapping’s concurrency cap or paused state
DELETE /api/mappings/{teamKey} removes a mapping

HTTP	`error`	Condition
400	`Invalid request body`	Body could not be parsed as JSON
400	`maxInProgressAiIssues must be a positive integer`	The new cap is below 1 or not an integer
400	`Specify either paused or maxInProgressAiIssues, not both`	The request set both fields at once
404	`Team not found`	No mapping with that team key

DELETE returns 404 with { "deleted": false } (no error field) when the mapping does not exist.

`POST /api/mappings/{teamKey}/sync-workflows`

Re-sync workflow templates into the mapping’s repository.

HTTP	`error`	Condition
404	`Team not found`	No mapping with that team key
500	(underlying error message)	The sync to GitHub failed

Jira configuration

POST /api/jira/validate-jql validates a JQL clause
GET /api/jira/fields lists Jira fields
GET /api/jira/field-options lists the options for a Jira field

HTTP	`error`	Condition
400	`Invalid JSON body`	The validate-jql body could not be parsed
400	`fieldId query param required`	`/api/jira/field-options` was called without `fieldId`
400	`jql field required`	The validate-jql body omitted `jql`
400	(validation message)	The JQL clause is invalid
500	(underlying error message)	The Jira request failed
501	`Jira not configured`	No Jira connection is configured on this orchestrator

/api/jira/field-options returns an empty list, not an error, when the field has no selectable options.

`POST /api/runner-mode`

Override the global runner execution mode.

HTTP	`error`	Condition
400	`Invalid request body`	Body could not be parsed as JSON
400	`mode must be one of: default, gha, fly, local, shadow`	`mode` is not a recognized value
409	`RUNNER_MODE env var is set; persisted to DB but has no effect at runtime until the env var is unset`	The value was saved, but a `RUNNER_MODE` environment variable overrides it at runtime

Sessions

GET /api/sessions lists active sessions
DELETE /api/sessions/{machineId} destroys a session

HTTP	`error`	Condition
500	(underlying error message)	Listing or destroying the session failed
503	`Fly sessions config not set`	Destroying a session while Fly sessions are not configured

GET /api/sessions returns an empty list, not an error, when Fly sessions are not configured.

Secrets

/api/mappings/{teamKey}/secrets lists, sets, and deletes per-team secrets
/api/global-secrets lists, sets, and deletes global secrets

HTTP	`error`	Condition
400	`Invalid request body`	Body could not be parsed as JSON
400	`name and value are required`	The secret name is missing, or the value is missing or empty
400	`name must contain only letters, digits, and underscores`	The secret name contains other characters
400	`Secret name must not start with a team key prefix (...)`	A global secret name collides with a team prefix
404	`Secret not found`	The named secret does not exist (on delete)
404	`Team not found`	No mapping with that team key (per-team secrets)
500	(underlying error message)	The secret operation failed
503	`Fly sessions config not set`	Secrets require Fly sessions to be configured

Deployments

POST /api/deploy starts a self-deploy
POST /api/deploy-policy changes what happens when a deployment becomes available

HTTP	`error`	Condition
400	`autoDeploy must be a boolean`	A policy switch was sent as something other than `true` or `false`; `notifyAvailable` reports the same way
409	`deploy-in-progress`	A deploy is already running
500	`Internal server error`	The deploy could not be started, or the policy body could not be parsed
501	`Self-deploy is not configured`	This orchestrator cannot deploy itself
503	`head-unknown`	The watched branch’s head could not be read

Dispatch breaker

GET /api/parked lists the issues the breaker has parked
POST /api/parked/unpark releases one

HTTP	`error`	Condition
400	`Invalid request body`	Body could not be parsed as JSON
400	`issueId is required`	The body carried no `issueId`, or carried one that was not a string

Unparking an issue that is not parked is not an error — it answers 200 with unparked: false.

Get Started

Setup

Optional setup

Configuration

Providers

Customize

Reference

Run statuses and failures

Troubleshooting

Response body shapes

Integration and callback API

`POST /runner/result`

`POST /runner/progress`

`GET /runner/planning-context`

`POST /trigger/gap-fill`

`POST /api/token`

`POST /api/status`

`POST /api/step-report`

`POST /api/github/webhook`

Admin API

`POST /api/auth`

Job steps and issue lists

`POST /api/mappings`

Mapping changes

`POST /api/mappings/{teamKey}/sync-workflows`

Jira configuration

`POST /api/runner-mode`

Sessions

Secrets

Deployments

Dispatch breaker

Run statuses and failures

Troubleshooting

​Response body shapes

​Integration and callback API

​POST /runner/result

​POST /runner/progress

​GET /runner/planning-context

​POST /trigger/gap-fill

​POST /api/token

​POST /api/status

​POST /api/step-report

​POST /api/github/webhook

​Admin API

​POST /api/auth

​Job steps and issue lists

​POST /api/mappings

​Mapping changes

​POST /api/mappings/{teamKey}/sync-workflows

​Jira configuration

​POST /api/runner-mode

​Sessions

​Secrets

​Deployments

​Dispatch breaker

Response body shapes

Integration and callback API

`POST /runner/result`

`POST /runner/progress`

`GET /runner/planning-context`

`POST /trigger/gap-fill`

`POST /api/token`

`POST /api/status`

`POST /api/step-report`

`POST /api/github/webhook`

Admin API

`POST /api/auth`

Job steps and issue lists

`POST /api/mappings`

Mapping changes

`POST /api/mappings/{teamKey}/sync-workflows`

Jira configuration

`POST /api/runner-mode`

Sessions

Secrets

Deployments

Dispatch breaker