Batch errors - Starfort

Batch errors split into two layers by when they occur:

Request / intake time — intake is rejected and no job is created. Returned immediately as an HTTP error response.
Processing time — intake succeeded, but the inspection couldn’t be completed, so the job finalizes as FAILED. The reason is provided in the job status response’s error (code / message / details).

BLOCK is not an error — it’s a normal verdict from a completed inspection, returned as COMPLETED + action: "BLOCK". See the batch overview.

Request / intake time (HTTP responses)

The error envelope is the same as the inline Guard API’s error format:

{
  "ok": false,
  "error": {
    "code": "S3_TARGET_NOT_ALLOWED",
    "message": "tgt_s3_url is outside the allowed write scope",
    "details": "connection 's3-prod' allows WRITE on s3://your-bucket/deidentified/*"
  }
}

HTTP	`error.code`	Situation
401	`UNAUTHORIZED`	API key missing or invalid
403	(active-state codes)	Deactivated, or a Kill Switch is active — while it’s on, both creation and queries are rejected
400	`BAD_REQUEST`	Malformed request — a bad URL format, an unsupported `process_type`, and so on
400	`S3_CONNECTION_NOT_CONFIGURED`	No Storage Connection registered on the project
400	`S3_TARGET_NOT_ALLOWED`	`src` / `tgt` falls outside the allowed scope (bucket · path · read/write mode)
404	`NOT_FOUND`	Querying a job ID that doesn’t exist
502	`BAD_GATEWAY`	A transient internal Starfort failure — retry

Processing-time failures (job `error.code`)

Returned in the job status response as status: "FAILED" with an error.code. A failed job writes nothing to tgt.

`error.code`	Situation
`SRC_FETCH_FAILED`	Couldn’t read the source — object missing, access denied, and so on
`SRC_UNSUPPORTED_TYPE`	Unsupported format, or extension/content mismatch (a disguised file)
`FILE_TOO_LARGE` / `TEXT_TOO_LONG`	File-size · text-length limit exceeded
`GUARDIAN_CALL_FAILED` / `GUARDIAN_REJECTED`	Analysis-engine processing failure — details in `details`
`TGT_WRITE_FAILED`	Couldn’t write the output — write permission, capacity, and so on
`KILL_SWITCH_ACTIVATED`	A Kill Switch fired after intake — waiting and in-progress jobs finalized as failed with no output
`JOB_EXPIRED`	Not completed within the retry budget — resubmit

Recommended handling

Check the HTTP status on job creation

202 = accepted (keep the job_id); 4xx/5xx = no job created — branch on error.code to correct the request or retry.

Branch on `status` when polling

COMPLETED = check the verdict (action); FAILED = branch on error.code.

Handle failures

For the SRC_* / S3_* family, fix the bucket, permissions, or file, then resubmit. For GUARDIAN_* / JOB_EXPIRED / 502, retry (resubmit) with backoff.

​Request / intake time (HTTP responses)

​Processing-time failures (job error.code)

​Recommended handling

Request / intake time (HTTP responses)

Processing-time failures (job `error.code`)

Recommended handling