Skip to content

Developer documentation

Error reference

Every error body has a stable code, a retryable flag, optional details and a link to its page here. Retry only when retryable is true, with the same Idempotency-Key.

HTTP errors

Returned as the body of a 4xx or 5xx response.

400COMPARE_RUN_REQUIRED

A comparison needs a second run.

400CONFIRMATION_REQUIRED

A consequential operation was sent without explicit confirmation.

400DISTINCT_RUNS_REQUIRED

A run cannot be compared with itself.

400IDEMPOTENCY_KEY_REQUIRED

Creates and external actions require an Idempotency-Key header.

400IDEMPOTENCY_KEY_TOO_LONG

The Idempotency-Key header exceeds 200 characters.

400INVALID_CURSOR

The pagination cursor is malformed or belongs to another listing.

400INVALID_PROVIDER

The provider filter is not a supported value.

400INVALID_REQUEST

The request body failed validation.

400INVALID_URL

The URL could not be parsed.

400KEY_EXPIRED

The requested key expiry is in the past or is not a valid date.

400PRIVATE_NETWORK_BLOCKED

The URL targets a private, local, or reserved network.

400SANSA_BILLING_PROFILE_REQUIRED

Metered requests require a billing profile.

400SANSA_OPERATION_REQUIRED

The x-sansa-operation-id header is missing or malformed.

400SANSA_TENANT_REQUIRED

The x-sansa-tenant-id header is missing or too long.

400UNSUPPORTED_PROTOCOL

Only http and https URLs are supported.

401UNAUTHENTICATED

No valid credential was presented.

402BUDGET_EXCEEDED

The run's maximum Context Units cannot be reserved within the remaining allowance.

402CLIENT_BUDGET_EXCEEDED

This client workspace has used its monthly Context Unit budget.

403FORBIDDEN

The credential or member role is not permitted to perform this operation.

403INTERACTION_SUBMIT_REQUIRES_ACTION_APPROVAL

Page interactions cannot submit forms.

403KEY_ENVIRONMENT_MISMATCH

The key's environment does not match this deployment.

403KEY_IP_NOT_ALLOWED

This API key has an IP allowlist and the request came from an address outside it.

403ORIGIN_MISMATCH

Browser key-management requests must come from the HoloSignal dashboard itself.

403OWNER_OR_ADMIN_REQUIRED

Only a workspace owner or admin can perform this operation.

403OWNER_SESSION_REQUIRED

Key management requires a signed-in owner or admin.

403PLAN_MEMBER_LIMIT

The workspace has reached its plan's member limit.

403PLAN_PROJECT_LIMIT

The workspace has reached its plan's project limit.

403PLAN_UPGRADE_REQUIRED

The workspace plan does not include this feature.

403REVIEWER_ROLE_REQUIRED

Only a workspace owner or admin can review packages.

403USER_SESSION_REQUIRED

This operation is only available to a signed-in user, not to API keys.

404ACTION_NOT_FOUND

The actionId in the outcome does not exist in this project.

404ACTION_OR_CONNECTOR_NOT_FOUND

The action, or an active connector for it, was not found in this project.

404BILLING_CUSTOMER_NOT_FOUND

The workspace has no billing account yet.

404COMPARE_RUN_NOT_FOUND

One of the runs being compared does not exist in this project.

404CONNECTOR_NOT_FOUND

The connector does not exist or is not active for this project.

404EXPORT_NOT_FOUND

The export file is no longer stored.

404INSTALL_NOT_FOUND

The installation does not exist in this project.

404NO_SCHEDULED_DELETION

There is no scheduled workspace deletion to cancel.

404NOT_FOUND

The resource does not exist in the credential's project.

404PACK_NOT_FOUND

The Context Pack or the requested version does not exist in this project.

404PACKAGE_NOT_FOUND

The package does not exist or is not owned by this workspace.

404PACKAGE_VERSION_NOT_FOUND

No visible version of this package matches the request.

404PARTNER_NOT_FOUND

The partner profile does not exist in this workspace.

404PLAN_NOT_FOUND

The requested plan does not exist or is no longer offered.

404REPLAY_SOURCE_NOT_FOUND

Only completed runs in this project can be replayed.

404TEMPLATE_NOT_FOUND

The report template does not exist or is not available to this workspace.

404TRACE_SHARE_NOT_FOUND

The shared trace link is invalid, revoked or expired.

409ACTION_HASH_CHANGED

The action changed after validation, so the approved argument hash no longer matches.

409ACTION_NOT_VALIDATED

Only a validated action can be approved.

409ALREADY_A_MEMBER

That email address already belongs to a member of this workspace.

409APPROVAL_INVALID_EXPIRED_USED_OR_DESTINATION_CHANGED

The action approval is no longer valid.

409BUDGET_NOT_CONFIGURED

The workspace has no active budget account.

409CONNECTOR_TYPE_MISMATCH

The connector cannot perform this type of action.

409DELIVERY_NOT_REPLAYABLE

This delivery has no stored event to resend.

409DEVELOPMENT_KEY_TEST_REQUIRED

A production key is issued only after a development key has made a successful call.

409DNS_TOKEN_NOT_FOUND

The domain's verification TXT record was not found.

409EMPTY_EVALUATION_SUITE

The evaluation suite has no cases to run.

409EMPTY_PROMPT_SET

The prompt set has no prompts to run.

409EXECUTED_ACTION_REQUIRED

Only an executed action can be verified.

409IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST

The Idempotency-Key was already used for a different request.

409IDEMPOTENCY_REQUEST_IN_PROGRESS

An earlier request with this Idempotency-Key is still being processed.

409INTERNAL_ZERO_SETTLEMENT

This workspace is settled internally and has no self-serve billing.

409INVALID_PACKAGE_TRANSITION

Only a draft package can be submitted for review.

409LAST_OWNER

The workspace's only owner cannot be demoted.

409NO_WORKSPACE

The signed-in user has no active workspace or project.

409ONE_TIME_SECRET_ALREADY_ISSUED

The request already succeeded, and its one-time secret cannot be shown again.

409PACK_EVALUATION_FAILED

The pack version did not pass its evaluation gate.

409PACK_NOT_PUBLISHED

The Context Pack has no production version to query.

409PACKAGE_NOT_IN_REVIEW

The package is not waiting for review.

409PACKAGE_VERSION_NOT_INSTALLABLE

Only a published version of a package can be installed.

409PRODUCTION_KEY_ALREADY_EXISTS

The project already has an active production key.

409QUALITY_GATE_NOT_MET

The result did not meet the requested quality threshold.

409ROTATION_CONFLICT

The key being rotated is no longer active.

409RUN_TERMINAL

The run has already finished and cannot be changed.

409WEBHOOK_HAS_NO_EVENTS

The webhook is not subscribed to any event type, so there is nothing to test.

410EXPORT_EXPIRED

The export download window has closed.

410EXPORT_OBJECT_MISSING

The export file is no longer available.

422BUDGET_ABOVE_PRICE_MAXIMUM

budget.maxUnits would cost more than this lane allows for one request.

422VISIBILITY_ENGINE_UNAVAILABLE

A requested answer engine is not available on this deployment.

429KEY_RATE_LIMITED

This API key sent more than 120 requests in one minute.

429RATE_LIMITED

Too many authentication or credential requests.

429WORKSPACE_RATE_LIMITED

The workspace exceeded 120 new runs per minute.

500IDEMPOTENCY_RESPONSE_NOT_JSON

The response for this Idempotency-Key could not be recorded, so the attempt was discarded.

500INTERNAL_ERROR

An unexpected error occurred.

502DESTINATION_WRITE_FAILED

The destination rejected or failed the approved write.

502DNS_LOOKUP_FAILED

The DNS lookup for the verification record failed.

502PROMPT_GENERATION_EMPTY

No usable question was generated for this category.

503BILLING_NOT_CONFIGURED

Billing is not configured on this deployment.

503CONNECTOR_ENCRYPTION_NOT_CONFIGURED

Connector credentials cannot be stored or used because encryption is not configured on this deployment.

503MARKETPLACE_SIGNING_UNAVAILABLE

This deployment cannot sign package versions right now, so the version was not created.

503PACK_NOT_CONFIGURED

This Context Unit pack is not on sale yet.

503PRICE_NOT_CONFIGURED

The selected plan and billing interval have no price on this deployment.

503PRIVACY_REQUEST_FAILED

The privacy request could not be recorded.

503PROMPT_GENERATION_UNAVAILABLE

Prompt suggestions could not be generated right now.

503RATE_CONTROL_UNAVAILABLE

Rate control could not be consulted, so the run was not accepted.

503SANSA_AUTH_NOT_CONFIGURED

Sansa Auth access is not configured on this deployment.

503SANSA_AUTH_UNAVAILABLE

Sansa Auth could not be reached to authorize the request.

503SERVICE_UNAVAILABLE

A dependency was temporarily unavailable.

503SUPPORT_DELIVERY_FAILED

The support message could not be delivered.

Run errors

Reported on a run: a failed run's error_code is RUN_FAILED or QUALITY_GATE_FAILED, and its error_message and events carry the specific cause.

runAGENT_MODEL_UNAVAILABLE

The research agent's model was not available for this run.

runAUTH_RESOLUTION_DEADLINE_PASSED

The run's Sansa Auth reservation expired before the run could start, so the run was stopped.

runBUDGET_EXHAUSTED

Some prompt × engine answers were skipped because the run's budget.maxUnits was used up.

runCANARY_FAULT_UNKNOWN_LIABILITY

A deliberate fault-injection test run was failed on purpose.

runCONCURRENCY_POOL_SATURATED

Too many runs were in progress, so this run waited for capacity.

runCRAWL_URL_REQUIRED

The crawl has no starting URL.

runDISCOVERY_RETURNED_NO_URLS

Discovery found no pages for the query.

runDOMAIN_BLOCKED_BY_POLICY

The page's domain is blocked by an active workspace or project policy, so it was not fetched.

runDOMAIN_RATE_CONTROL_FAILED

Per-domain rate control could not be consulted, so the page was not fetched.

runDOMAIN_RATE_LIMITED

Fetching from this site was paused to respect its per-domain rate limit.

runFETCH_URL_REQUIRED

The fetch has no URL.

runINTERACTION_URL_REQUIRED

The interaction has no URL.

runMODEL_BUDGET_EXHAUSTED

External answer engines were skipped because HoloSignal's monthly budget for them is used up.

runNO_PACK_EVIDENCE

Nothing in the pack matched the query.

runNO_RESULTS_MATCH_DOMAIN_FILTER

No pages were found on the domains you restricted the search to.

runNO_RESULTS_MATCH_FILTERS

Pages were found, but none passed the request's filters.

runNO_USABLE_EVIDENCE

Pages were found, but none yielded usable evidence.

runPACK_HAS_NO_SOURCES

The pack version has no sources.

runPACK_VERSION_REQUIRED

The pack query has no pack version to read.

runPDF_NOT_SUPPORTED

The URL points to a PDF, which cannot be fetched yet.

runPROMPT_SET_NOT_FOUND

The visibility run's prompt set no longer exists or was archived.

runQUALITY_GATE_FAILED

The run finished without any usable evidence.

runREPLAY_SOURCE_REQUIRED

The replay did not name the run to replay.

runRETRYING

The run hit a temporary failure and is queued to retry automatically.

runRUN_COORDINATION_FAILED

The run could not be marked as started.

runRUN_FAILED

The run failed after its automatic retries.

runSANSAAI_ACQUISITION_CANCELLED

The page fetch was cancelled before it finished.

runSANSAAI_ACQUISITION_DENIED

The acquisition provider's policy refused to fetch the page.

runSANSAAI_ACQUISITION_FAILED

The acquisition provider could not fetch the page. Its reason follows the colon, when present.

runSANSAAI_ACQUISITION_RECEIPT_MISSING

The page was fetched without a usage receipt, so its content was not used.

runSANSAAI_ACQUISITION_TIMEOUT

The page fetch did not finish in time.

runSANSAAI_ARTIFACT_DIGEST_MISMATCH

The fetched content failed its integrity check, so it was discarded.

runSANSAAI_ARTIFACT_ENCODING_INVALID

The fetched content had an invalid encoding, so it was discarded.

runSANSAAI_ARTIFACT_EXPIRED

The fetched content expired before it could be read.

runSANSAAI_ARTIFACT_RECEIPT_MISMATCH

The fetched content was not linked to its usage receipt, so it was discarded.

runSANSAAI_AUTHENTICATION_REQUIRED

HoloSignal's credentials for page acquisition were rejected.

runSANSAAI_INSUFFICIENT_SCOPE

HoloSignal is not permitted to use this acquisition capability.

runSANSAAI_NOT_CONFIGURED

Page acquisition is not configured on this deployment.

runSANSAAI_OPERATION_ID_INVALID

The acquisition request had an invalid operation id.

runSANSAAI_POLICY_DENIED

The acquisition provider's policy refused the request.

runSANSAAI_RATE_LIMIT_EXCEEDED

The acquisition provider is rate limiting requests.

runSANSAAI_REDIRECT_DENIED

The acquisition provider tried to redirect the request, which is refused.

runSANSAAI_RESPONSE_INVALID

The acquisition provider returned a malformed response.

runSANSAAI_RESPONSE_TOO_LARGE

The acquisition provider's response exceeded the size limit.

runSANSAAI_TOKEN_DENIED

Sansa Auth refused to issue a page-acquisition token.

runSANSAAI_TOKEN_UNAVAILABLE

Sansa Auth could not issue a page-acquisition token.

runSANSAAI_UNREACHABLE

The acquisition provider could not be reached.

runSCHEMA_INVALID_OUTPUT

The answer did not match your outputSchema. Failing locations follow the colon in error_message.

runVISIBILITY_NO_ANSWERS

No answer engine returned an answer for this visibility run; nothing was charged for the failed answers.

MCP tool errors

Returned inside a tool result by the HoloSignal MCP server. API errors pass through unchanged.