API governance

Failure semantics are part of the contract.

A production client must preserve admission failures, partial coverage and terminal job state instead of flattening them into success or absence.

Follow quickstart Product reference

Machine errors

Branch on code, not message text.

This table is generated from the stable machine-code extension in the current v2 OpenAPI document.

Public API v2 stable machine error codes
Code	HTTP	Meaning	Retryable	Retry-After
`active_authorization_required`	403	Advanced or active work needs explicit request authorization.	No automatic retry	Not defined
`active_permission_required`	403	The workspace has not granted the required active capability.	No automatic retry	Not defined
`approved_target_scope_required`	403	The active target is outside the approved workspace scope.	No automatic retry	Not defined
`authentication_required`	401	A valid application Bearer key is required.	No automatic retry	Not defined
`capability_rate_limit_exceeded`	429	The product-specific minute or hour limit was reached.	Yes, after the condition changes	Use header when present
`capability_unavailable`	503	A required public product lane is not currently available.	Yes, after the condition changes	Not defined
`idempotency_key_conflict`	409	The key was already bound to a different normalized request.	No automatic retry	Not defined
`idempotency_key_required`	400	A bounded visible Idempotency-Key is required for this write.	No automatic retry	Not defined
`idempotency_request_in_progress`	409	An identical idempotent request is still processing.	Yes, after the condition changes	Use header when present
`insufficient_credits`	402	The account has insufficient available execution credits.	No automatic retry	Not defined
`insufficient_scope`	403	The application key lacks the required operation scope.	No automatic retry	Not defined
`job_not_found`	404	The job does not exist in the authorized tenant scope.	No automatic retry	Not defined
`monthly_credit_limit_exceeded`	402	The application key monthly credit ceiling would be exceeded.	No automatic retry	Not defined
`object_not_found`	404	The retained object does not exist in this job scope.	No automatic retry	Not defined
`rate_limit_exceeded`	429	The application request rate limit was reached.	Yes, after the condition changes	Use header when present
`responsible_use_required`	403	Current responsible-use acceptance is required.	No automatic retry	Not defined
`scan_credit_budget_invalid`	400	The requested maxCredits is invalid for the selected profile.	No automatic retry	Not defined
`scan_profile_unavailable`	503	The selected public profile is unavailable.	Yes, after the condition changes	Not defined
`service_unavailable`	503	The public execution dependency is unavailable.	Yes, after the condition changes	Not defined

Rate limits

Application and capability minute/hour limits are independent. On 429, honor Retry-After when present and use bounded backoff. Changing keys or idempotency values to evade a limit is not a retry strategy.

Credits

Paid writes reserve before dispatch, then capture measured work and release unused reservation once. A 402 denial dispatches no paid operation. Job status can include the terminal ledger summary.

Idempotency

A write key binds normalized method, path and intent. Retry an uncertain identical request with the same key. Reusing it for different input returns idempotency_key_conflict.

Coverage

Keep partial and unavailable visible.

Availability and completeness are observable states. They are not interchangeable with a clean assessment.

Partial lookup

A required projection may complete while an optional lane is unavailable. Preserve lane status, source summary and limitations with the useful retained fields.

Partial job

Results and findings can be paged before or after terminal completion. Their status, coverage, page cursor and limitations disclose whether the loaded view is partial.

No all-clear

No matched finding, a timeout, an unconfigured provider or an unavailable lane does not prove absence, safety, ownership or complete coverage.

Downstream reports and alerts must retain coverage and limitation fields. Do not convert partial or unavailable into a successful negative conclusion.

Cancellation

A request, not a rewrite of history.

POST /v2/jobs/{job_ref}/cancel is an idempotent, tenant-scoped request. It asks the existing orchestrator to stop future scheduling and cancel queued work.

Already terminal jobs remain terminal. In-flight work reaches a durable state according to the existing cancellation boundary. Poll the job route for the resulting cancelled, partial or other terminal outcome.

Evidence and provenance

Read references without exposing backend custody.

The public lifecycle exposes allowlisted canonical result, finding and object projections with evidence summaries and source references.

Use results and object detail to follow retained canonical IDs and public evidence references. Findings require finding:read. There is no v2 raw-evidence-bytes route; service tokens, provider credentials, raw internal events and database identifiers remain private.