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

​
Status codes

StatusMeaning
200Successful GET or PATCH.
201Successful POST — a new resource was created.
204Successful request with no response body (for example, revoking a key).
400Bad request. Typically a validation failure; message identifies the field that failed validation.
401Missing, malformed, revoked, or expired API key.
402Payment required. Returned by POST /scans when the organization has insufficient Whitebox Scan credits.
403Your API key does not have the required scope.
404The resource does not exist, or is not visible to your organization.
409Conflict. For example, exceeding the maximum active API key count when creating a new key.
429Rate limit exceeded. See Rate limits.
500Unexpected server error. Safe to retry with backoff; contact support if it persists.

​
Error body shape

Errors are returned as JSON with a consistent shape: 
{
  "statusCode": 400,
  "message": "At least one repository is required",
  "error": "Bad Request"
}
Validation errors may return message as an array of field‑level errors: 
{
  "statusCode": 400,
  "message": [
    "repos must contain at least 1 elements",
    "cost_estimation_id must be a UUID"
  ],
  "error": "Bad Request"
}

​
Common failure modes

​
”This endpoint requires API key authentication”

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.