Skip to main content
The Hacktron REST API uses standard HTTP status codes to indicate success and failure.

​
Status codes

​
Error body shape

Errors are returned as JSON with a consistent shape:
Validation errors may return message as an array of field‑level errors:

​
Common failure modes

​
”This endpoint requires API key authentication (X-Api-Key header)”

A REST endpoint was called with a dashboard session token instead of an API key. REST endpoints under /v1/* require the X-Api-Key header.

​
”API key authentication is only supported on /api/v1/rest/ endpoints”

This only appears when calling the backend route directly instead of the public API host. Use the public base URL from Introduction and call /v1/* endpoints with X-Api-Key. Dashboard endpoints use session authentication and are not part of this API reference.

​
”API key missing required scope: write”

The key was created with read only but the request targets a write endpoint. Create a new key that includes the write scope and retry.

​
”Insufficient credits to start this scan”

The organization does not have enough Whitebox Scan credits for the requested scan. Top up from Credits and billing in the dashboard, or submit a smaller cost estimation.

​
”cost_estimation_id is required for pentest scans”

Whitebox Scan-only inputs such as target_urls, auth_instructions, custom_context, or context_document_ids require a cost estimation so credits can be deducted correctly. Create a cost estimation first, then pass its id as cost_estimation_id.

​
”Cost estimation is not ready”

The estimation is still pending or running. Poll GET /cost-estimations/{id} until the status reaches completed or partial before starting the scan.

​
”Repository or archive … was not included in the cost estimation”

The scan request does not match the repositories or uploaded archive that were estimated. Create a new estimate for the exact scope you want to scan.

​
”Branch … does not match the cost estimation branch”

The repository URL matches the estimate, but the branch does not. Start the scan with the same branch used for estimation, or create a new estimate for the new branch.

​
”Finding not found”

Returned when the finding does not exist, has not yet reached the approved verification state, or belongs to a different organization. Hacktron does not distinguish between these cases in the response to avoid leaking cross‑tenant information.