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.
COMPARE_RUN_REQUIREDA comparison needs a second run.
400CONFIRMATION_REQUIREDA consequential operation was sent without explicit confirmation.
400DISTINCT_RUNS_REQUIREDA run cannot be compared with itself.
400IDEMPOTENCY_KEY_REQUIREDCreates and external actions require an Idempotency-Key header.
400IDEMPOTENCY_KEY_TOO_LONGThe Idempotency-Key header exceeds 200 characters.
400INVALID_CURSORThe pagination cursor is malformed or belongs to another listing.
400INVALID_PROVIDERThe provider filter is not a supported value.
400INVALID_REQUESTThe request body failed validation.
400INVALID_URLThe URL could not be parsed.
400KEY_EXPIREDThe requested key expiry is in the past or is not a valid date.
400PRIVATE_NETWORK_BLOCKEDThe URL targets a private, local, or reserved network.
400SANSA_BILLING_PROFILE_REQUIREDMetered requests require a billing profile.
400SANSA_OPERATION_REQUIREDThe x-sansa-operation-id header is missing or malformed.
400SANSA_TENANT_REQUIREDThe x-sansa-tenant-id header is missing or too long.
400UNSUPPORTED_PROTOCOLOnly http and https URLs are supported.
401UNAUTHENTICATEDNo valid credential was presented.
402BUDGET_EXCEEDEDThe run's maximum Context Units cannot be reserved within the remaining allowance.
402CLIENT_BUDGET_EXCEEDEDThis client workspace has used its monthly Context Unit budget.
403FORBIDDENThe credential or member role is not permitted to perform this operation.
403INTERACTION_SUBMIT_REQUIRES_ACTION_APPROVALPage interactions cannot submit forms.
403KEY_ENVIRONMENT_MISMATCHThe key's environment does not match this deployment.
403KEY_IP_NOT_ALLOWEDThis API key has an IP allowlist and the request came from an address outside it.
403ORIGIN_MISMATCHBrowser key-management requests must come from the HoloSignal dashboard itself.
403OWNER_OR_ADMIN_REQUIREDOnly a workspace owner or admin can perform this operation.
403OWNER_SESSION_REQUIREDKey management requires a signed-in owner or admin.
403PLAN_MEMBER_LIMITThe workspace has reached its plan's member limit.
403PLAN_PROJECT_LIMITThe workspace has reached its plan's project limit.
403PLAN_UPGRADE_REQUIREDThe workspace plan does not include this feature.
403REVIEWER_ROLE_REQUIREDOnly a workspace owner or admin can review packages.
403USER_SESSION_REQUIREDThis operation is only available to a signed-in user, not to API keys.
404ACTION_NOT_FOUNDThe actionId in the outcome does not exist in this project.
404ACTION_OR_CONNECTOR_NOT_FOUNDThe action, or an active connector for it, was not found in this project.
404BILLING_CUSTOMER_NOT_FOUNDThe workspace has no billing account yet.
404COMPARE_RUN_NOT_FOUNDOne of the runs being compared does not exist in this project.
404CONNECTOR_NOT_FOUNDThe connector does not exist or is not active for this project.
404EXPORT_NOT_FOUNDThe export file is no longer stored.
404INSTALL_NOT_FOUNDThe installation does not exist in this project.
404NO_SCHEDULED_DELETIONThere is no scheduled workspace deletion to cancel.
404NOT_FOUNDThe resource does not exist in the credential's project.
404PACK_NOT_FOUNDThe Context Pack or the requested version does not exist in this project.
404PACKAGE_NOT_FOUNDThe package does not exist or is not owned by this workspace.
404PACKAGE_VERSION_NOT_FOUNDNo visible version of this package matches the request.
404PARTNER_NOT_FOUNDThe partner profile does not exist in this workspace.
404PLAN_NOT_FOUNDThe requested plan does not exist or is no longer offered.
404REPLAY_SOURCE_NOT_FOUNDOnly completed runs in this project can be replayed.
404TEMPLATE_NOT_FOUNDThe report template does not exist or is not available to this workspace.
404TRACE_SHARE_NOT_FOUNDThe shared trace link is invalid, revoked or expired.
409ACTION_HASH_CHANGEDThe action changed after validation, so the approved argument hash no longer matches.
409ACTION_NOT_VALIDATEDOnly a validated action can be approved.
409ALREADY_A_MEMBERThat email address already belongs to a member of this workspace.
409APPROVAL_INVALID_EXPIRED_USED_OR_DESTINATION_CHANGEDThe action approval is no longer valid.
409BUDGET_NOT_CONFIGUREDThe workspace has no active budget account.
409CONNECTOR_TYPE_MISMATCHThe connector cannot perform this type of action.
409DELIVERY_NOT_REPLAYABLEThis delivery has no stored event to resend.
409DEVELOPMENT_KEY_TEST_REQUIREDA production key is issued only after a development key has made a successful call.
409DNS_TOKEN_NOT_FOUNDThe domain's verification TXT record was not found.
409EMPTY_EVALUATION_SUITEThe evaluation suite has no cases to run.
409EMPTY_PROMPT_SETThe prompt set has no prompts to run.
409EXECUTED_ACTION_REQUIREDOnly an executed action can be verified.
409IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUESTThe Idempotency-Key was already used for a different request.
409IDEMPOTENCY_REQUEST_IN_PROGRESSAn earlier request with this Idempotency-Key is still being processed.
409INTERNAL_ZERO_SETTLEMENTThis workspace is settled internally and has no self-serve billing.
409INVALID_PACKAGE_TRANSITIONOnly a draft package can be submitted for review.
409LAST_OWNERThe workspace's only owner cannot be demoted.
409NO_WORKSPACEThe signed-in user has no active workspace or project.
409ONE_TIME_SECRET_ALREADY_ISSUEDThe request already succeeded, and its one-time secret cannot be shown again.
409PACK_EVALUATION_FAILEDThe pack version did not pass its evaluation gate.
409PACK_NOT_PUBLISHEDThe Context Pack has no production version to query.
409PACKAGE_NOT_IN_REVIEWThe package is not waiting for review.
409PACKAGE_VERSION_NOT_INSTALLABLEOnly a published version of a package can be installed.
409PRODUCTION_KEY_ALREADY_EXISTSThe project already has an active production key.
409QUALITY_GATE_NOT_METThe result did not meet the requested quality threshold.
409ROTATION_CONFLICTThe key being rotated is no longer active.
409RUN_TERMINALThe run has already finished and cannot be changed.
409WEBHOOK_HAS_NO_EVENTSThe webhook is not subscribed to any event type, so there is nothing to test.
410EXPORT_EXPIREDThe export download window has closed.
410EXPORT_OBJECT_MISSINGThe export file is no longer available.
422BUDGET_ABOVE_PRICE_MAXIMUMbudget.maxUnits would cost more than this lane allows for one request.
422VISIBILITY_ENGINE_UNAVAILABLEA requested answer engine is not available on this deployment.
429KEY_RATE_LIMITEDThis API key sent more than 120 requests in one minute.
429RATE_LIMITEDToo many authentication or credential requests.
429WORKSPACE_RATE_LIMITEDThe workspace exceeded 120 new runs per minute.
500IDEMPOTENCY_RESPONSE_NOT_JSONThe response for this Idempotency-Key could not be recorded, so the attempt was discarded.
500INTERNAL_ERRORAn unexpected error occurred.
502DESTINATION_WRITE_FAILEDThe destination rejected or failed the approved write.
502DNS_LOOKUP_FAILEDThe DNS lookup for the verification record failed.
502PROMPT_GENERATION_EMPTYNo usable question was generated for this category.
503BILLING_NOT_CONFIGUREDBilling is not configured on this deployment.
503CONNECTOR_ENCRYPTION_NOT_CONFIGUREDConnector credentials cannot be stored or used because encryption is not configured on this deployment.
503MARKETPLACE_SIGNING_UNAVAILABLEThis deployment cannot sign package versions right now, so the version was not created.
503PACK_NOT_CONFIGUREDThis Context Unit pack is not on sale yet.
503PRICE_NOT_CONFIGUREDThe selected plan and billing interval have no price on this deployment.
503PRIVACY_REQUEST_FAILEDThe privacy request could not be recorded.
503PROMPT_GENERATION_UNAVAILABLEPrompt suggestions could not be generated right now.
503RATE_CONTROL_UNAVAILABLERate control could not be consulted, so the run was not accepted.
503SANSA_AUTH_NOT_CONFIGUREDSansa Auth access is not configured on this deployment.
503SANSA_AUTH_UNAVAILABLESansa Auth could not be reached to authorize the request.
503SERVICE_UNAVAILABLEA dependency was temporarily unavailable.
503SUPPORT_DELIVERY_FAILEDThe 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.
AGENT_MODEL_UNAVAILABLEThe research agent's model was not available for this run.
runAUTH_RESOLUTION_DEADLINE_PASSEDThe run's Sansa Auth reservation expired before the run could start, so the run was stopped.
runBUDGET_EXHAUSTEDSome prompt × engine answers were skipped because the run's budget.maxUnits was used up.
runCANARY_FAULT_UNKNOWN_LIABILITYA deliberate fault-injection test run was failed on purpose.
runCONCURRENCY_POOL_SATURATEDToo many runs were in progress, so this run waited for capacity.
runCRAWL_URL_REQUIREDThe crawl has no starting URL.
runDISCOVERY_RETURNED_NO_URLSDiscovery found no pages for the query.
runDOMAIN_BLOCKED_BY_POLICYThe page's domain is blocked by an active workspace or project policy, so it was not fetched.
runDOMAIN_RATE_CONTROL_FAILEDPer-domain rate control could not be consulted, so the page was not fetched.
runDOMAIN_RATE_LIMITEDFetching from this site was paused to respect its per-domain rate limit.
runFETCH_URL_REQUIREDThe fetch has no URL.
runINTERACTION_URL_REQUIREDThe interaction has no URL.
runMODEL_BUDGET_EXHAUSTEDExternal answer engines were skipped because HoloSignal's monthly budget for them is used up.
runNO_PACK_EVIDENCENothing in the pack matched the query.
runNO_RESULTS_MATCH_DOMAIN_FILTERNo pages were found on the domains you restricted the search to.
runNO_RESULTS_MATCH_FILTERSPages were found, but none passed the request's filters.
runNO_USABLE_EVIDENCEPages were found, but none yielded usable evidence.
runPACK_HAS_NO_SOURCESThe pack version has no sources.
runPACK_VERSION_REQUIREDThe pack query has no pack version to read.
runPDF_NOT_SUPPORTEDThe URL points to a PDF, which cannot be fetched yet.
runPROMPT_SET_NOT_FOUNDThe visibility run's prompt set no longer exists or was archived.
runQUALITY_GATE_FAILEDThe run finished without any usable evidence.
runREPLAY_SOURCE_REQUIREDThe replay did not name the run to replay.
runRETRYINGThe run hit a temporary failure and is queued to retry automatically.
runRUN_COORDINATION_FAILEDThe run could not be marked as started.
runRUN_FAILEDThe run failed after its automatic retries.
runSANSAAI_ACQUISITION_CANCELLEDThe page fetch was cancelled before it finished.
runSANSAAI_ACQUISITION_DENIEDThe acquisition provider's policy refused to fetch the page.
runSANSAAI_ACQUISITION_FAILEDThe acquisition provider could not fetch the page. Its reason follows the colon, when present.
runSANSAAI_ACQUISITION_RECEIPT_MISSINGThe page was fetched without a usage receipt, so its content was not used.
runSANSAAI_ACQUISITION_TIMEOUTThe page fetch did not finish in time.
runSANSAAI_ARTIFACT_DIGEST_MISMATCHThe fetched content failed its integrity check, so it was discarded.
runSANSAAI_ARTIFACT_ENCODING_INVALIDThe fetched content had an invalid encoding, so it was discarded.
runSANSAAI_ARTIFACT_EXPIREDThe fetched content expired before it could be read.
runSANSAAI_ARTIFACT_RECEIPT_MISMATCHThe fetched content was not linked to its usage receipt, so it was discarded.
runSANSAAI_AUTHENTICATION_REQUIREDHoloSignal's credentials for page acquisition were rejected.
runSANSAAI_INSUFFICIENT_SCOPEHoloSignal is not permitted to use this acquisition capability.
runSANSAAI_NOT_CONFIGUREDPage acquisition is not configured on this deployment.
runSANSAAI_OPERATION_ID_INVALIDThe acquisition request had an invalid operation id.
runSANSAAI_POLICY_DENIEDThe acquisition provider's policy refused the request.
runSANSAAI_RATE_LIMIT_EXCEEDEDThe acquisition provider is rate limiting requests.
runSANSAAI_REDIRECT_DENIEDThe acquisition provider tried to redirect the request, which is refused.
runSANSAAI_RESPONSE_INVALIDThe acquisition provider returned a malformed response.
runSANSAAI_RESPONSE_TOO_LARGEThe acquisition provider's response exceeded the size limit.
runSANSAAI_TOKEN_DENIEDSansa Auth refused to issue a page-acquisition token.
runSANSAAI_TOKEN_UNAVAILABLESansa Auth could not issue a page-acquisition token.
runSANSAAI_UNREACHABLEThe acquisition provider could not be reached.
runSCHEMA_INVALID_OUTPUTThe answer did not match your outputSchema. Failing locations follow the colon in error_message.
runVISIBILITY_NO_ANSWERSNo 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.