Core concepts

Errors

All Pentify API errors share a single envelope. The code field is stable — switch on it in client code. The message field is for humans and may change.

{
  "error": {
    "code": "stable_machine_code",
    "message": "Human-readable message.",
    "details": { "...optional..." },
    "request_id": "req_01HFY3..."
  }
}

code is stable — promote it through alerting and switch on it in client code. New codes are additive.
message is for humans. It can change between releases. Don’t pattern-match.
details is endpoint-specific.
request_id is always present. Quote it in support tickets.

Common codes

HTTP

code

Meaning

Retry?

400

validation_error

Request body or query is malformed.

401

invalid_api_key

Missing, malformed, or revoked key.

403

insufficient_scope

Key lacks the scope this endpoint needs.

403

target_not_verified

Scan attempted on an unverified target.

After verifying

404

not_found

Resource does not exist or is invisible to this key.

409

conflict

Resource state forbids the operation.

402

insufficient_tokens

Workspace balance below operation cost.

After top-up

422

unprocessable

Semantically rejected (e.g. unsupported scan_type).

429

rate_limited

Too many requests per minute for this key.

Yes — see Retry-After

500

server_error

Pentify internal failure.

Yes — exponential backoff

503

engine_unavailable

Scan engine degraded.

Yes — backoff

Retry guidance

Idempotent retries: GET and DELETE are always safe to retry.
Mutating retries: POST /v1/scans returns the existing scan when called with a deterministic idempotency_key — set one to retry safely.
Backoff: start at 1s, double, jitter ±25%, cap at 30s, give up after 5 attempts. The official SDKs do this for you on 429 and 5xx.

SDK error subclasses

Each SDK wraps the envelope in a typed error.

SDK	Base class	Examples
TypeScript	`PentifyError`	`InvalidApiKeyError`, `InsufficientTokensError`, `RateLimitedError`, `TargetNotVerifiedError`, `ValidationError`
Python	`PentifyError`	Same names, snake_case modules.
Go	`pentify.APIError`	Inspect `err.Code` (e.g. `pentify.CodeInsufficientTokens`).

Note

See per-SDK pages: TypeScript, Python, Go.