Errors and retry decisions

Branch on stable error codes and retry only operations that are safe and transient.

Public API failures use OpenAPI schema ErrorResponse:

{
  "error": {
    "code": "invalid_request",
    "message": "A readable explanation of what went wrong.",
    "request_id": "req_example",
    "docs_url": "https://engine.neraperla.com/docs/errors"
  }
}

Use error.code, not HTTP status alone, to decide what happens next. Preserve request_id for diagnostics. Validation failures, quota refusals, and budget refusals also include structured details. Every /v1 path returns this envelope, including an unknown path (404 not_found) and a method the path doesn't support (405 with invalid_request).

A failed job reports its failure in the job body rather than as an HTTP error: error carries the message, and error_code carries a code from this vocabulary when one applies.

Error and retry matrix#

CodesStatusRetry?Caller action
invalid_request, invalid_cursor, invalid_domain, brand_profile_mismatch, invalid_campaign_key, invalid_campaign_metadata, invalid_campaign_name, invalid_campaign_objective, invalid_campaign_status, campaign_relation_mismatch, invalid_stage400 or 422NoCorrect the request. invalid_request also answers 405 when the path doesn't support the HTTP method.
project_required400NoA company-level key without a default project made a request that needs a project without naming one: send the Blackpearl-Project header with the project's id or slug. See Authentication and Managing your clients with projects.
missing_api_key, invalid_api_key, expired_api_key, authentication_required401NoSupply an active API key.
insufficient_credits402NoLet auto-recharge complete or add credits. Admission only requires a positive balance; a run that finishes above the remaining balance still succeeds and takes the balance negative, which blocks new runs until a top-up.
forbidden, project_archived, capability_disabled403NoChange the key, project state, or access. forbidden includes a project key naming another project (in Blackpearl-Project or a /v1/projects/{project_ref} path) and a project key calling an operation only a company-level key can use. project_archived means the key's project, the named project, or a company-level key's default project is archived; restore it or use an active project. For capability_disabled, call GET /v1/capabilities to see which capabilities are enabled; the capability exists but is not enabled for the organization, so request access.
project_not_found404NoThe project named by Blackpearl-Project or the path doesn't exist in the organization; check the id or slug, or list projects with GET /v1/projects.
not_found, result_unavailable, playbooks_document_unavailable, brand_not_found, brand_profile_not_found, offer_not_found, account_not_found, playbook_job_not_found, message_template_revision_not_found, company_dossier_specification_not_found404NoCheck the ID or domain, project ownership, environment, and retained data. A resource in another project returns not_found to a project key. not_found also answers an unknown /v1 path.
job_expired410NoUse the result stored by the client or create a new job.
not_ready, job_not_finished, audiences_result_unavailable, idempotency_in_progress, prospecting_continuation_in_progress409Yes, after delayContinue the documented read/poll flow or repeat the same idempotent request. For prospecting_continuation_in_progress, another continuation of the same search is still running: poll its child Job and retry when it finishes.
conflict, idempotency_key_reused, campaign_archived, campaign_key_exists, invalid_campaign_transition, cycle_in_progress, offer_archived, brand_profile_archived, brand_profile_not_ready, brand_guideline_missing, missing_default_brand_profile, playbook_template_not_ready409NoRead or repair resource state; use a new idempotency key for changed input. conflict includes a project slug that is already in use, an allowance top-up or reduction reference already used for a different amount or for the other kind of entry, and a reduction that would take a project's total granted below zero. brand_profile_archived also answers a run that names no brand when its project's default brand is archived. For playbook_template_not_ready, wait for the template's one-time research to finish (or retry it from the template page).
account_unanalyzable422NoCheck that the domain serves a fetchable public website or continue without on-demand analysis.
rate_limit_exceeded429YesWait at least Retry-After, then retry with backoff and jitter.
quota_exceeded429No automatic retryInspect error.details for scope, counters, and resets_at; wait for reset or change the quota.
budget_exceeded429No automatic retryInspect error.details: scope (organization, project, or usage_tier), kind (day, month, allowance, or min_to_start), project_id, period, charged spend_usd, limit_usd, remaining_usd, and resets_at. For a daily or monthly limit, raise the hard budget or limit, or wait for resets_at. A project's allowance (kind allowance or min_to_start) has no reset, so period and resets_at are null and held_usd and min_to_start_usd show what runs in progress hold and what a new run needs: top it up (see Managing your clients with projects). When scope is "usage_tier", the organization's tier-based monthly cap was reached — the cap rises automatically as the organization purchases credits and builds account history (see Rate limits for the ladder), or support can adjust the tier.
account_research_backend_quota429No automatic retryWait for the research capacity to reset or ask an operator to increase it.
audiences_backend_error, audiences_backend_invalid_response, audiences_backend_unavailable502 or 503Bounded retry for safe readsBack off with jitter; report persistent failures with request_id.
enrichment_backend_error, enrichment_backend_invalid_response, enrichment_backend_unavailable502 or 503Bounded retryThe run is failed and never billed. enrichment_backend_unavailable also covers a deploy restart and briefly saturated synchronous capacity — honor the Retry-After header when present, otherwise back off with jitter; report persistent failures with request_id.
enrichment_backend_not_configured503NoEnrichment is not configured on this deployment; ask an operator.
account_research_backend_error, account_research_unavailable502 or 503Bounded retryBack off with jitter; report persistent failures with request_id.
account_research_unauthorized502NoAsk an operator to repair the platform's research-backend credential.
account_research_not_configured500NoAsk an operator to configure the organization's research-backend identity.
internal_error500Safe reads onlyRetry a GET with bounds. Do not automatically repeat job creation.

Endpoint-specific codes#

The OpenAPI PublicErrorCode enum is the authoritative finite vocabulary. The matrix above describes the shared codes; the more precise endpoint codes below preserve which resource, snapshot, policy, or idempotency rule failed. These codes are non-retryable unless the endpoint guide explicitly describes the state change required before retrying. Clients should still retain a default branch for forward-compatible additions.

  • Capability failures (403): documents_capability_disabled, professional_network_capability_disabled, prospect_research_capability_disabled.

  • Scoped resource failures (404): assessment_not_found, audience_member_not_found, audience_not_found, campaign_not_found, company_dossier_connection_not_found, connection_not_found, data_intake_specification_not_found, playbook_template_not_found, professional_network_connection_not_found, professional_network_specification_not_found, prospect_not_found, prospect_research_specification_not_found, prospecting_job_not_found, qualification_policy_not_found, site_audit_specification_not_found.

  • State, version, idempotency, and limit conflicts (409): account_coordination_evidence_too_large, account_coordination_idempotency_conflict, account_coordination_policy_not_current, audience_idempotency_conflict, audience_result_changed, audience_review_idempotency_conflict, audience_source_changed, company_dossier_connection_credentials_changed, company_dossier_connection_incomplete, company_dossier_connector_manifest_changed, company_dossier_policy_not_current, company_dossier_specification_idempotency_conflict, company_dossier_specification_limit_exceeded, company_dossier_specification_limit_reached, data_intake_policy_not_current, data_intake_specification_idempotency_conflict, data_intake_specification_limit_exceeded, data_intake_specification_limit_reached, enrichment_input_invalid, message_template_hash_conflict, message_template_key_revision_limit_reached, message_template_policy_not_current, message_template_previous_hash_conflict, message_template_revision_idempotency_conflict, message_template_revision_limit_exceeded, message_template_revision_limit_reached, message_template_revision_renderer_unavailable, message_template_revision_sequence_conflict, offer_key_exists, offer_limit_exceeded, outcome_idempotency_conflict, professional_network_audience_changed, professional_network_audience_source_changed, professional_network_audience_source_invalid, professional_network_connection_incomplete, professional_network_connector_manifest_changed, professional_network_connector_unavailable, professional_network_credentials_changed, professional_network_policy_not_current, professional_network_selection_too_large, professional_network_specification_idempotency_conflict, professional_network_specification_limit_exceeded, professional_network_specification_limit_reached, prospect_research_audience_changed, prospect_research_audience_source_changed, prospect_research_audience_source_invalid, prospect_research_policy_not_current, prospect_research_selection_too_large, prospect_research_specification_idempotency_conflict, prospect_research_specification_limit_exceeded, prospect_research_specification_limit_reached, prospecting_continuation_idempotency_conflict, prospecting_continuation_unavailable, prospecting_job_not_ready, prospecting_parent_changed, prospecting_result_unavailable, qualification_policy_idempotency_conflict, qualification_policy_limit_exceeded, qualification_policy_limit_reached, qualification_policy_not_current, site_audit_policy_not_current, site_audit_specification_idempotency_conflict, site_audit_specification_limit_exceeded, site_audit_specification_limit_reached. audience_source_unavailable can be 409 or 422 depending on whether the source changed or is invalid for the requested operation.

  • Endpoint validation failures (422): audience_empty, enrichment_fields_unsupported, enrichment_level_unavailable, invalid_insight_group, invalid_offer_field, invalid_offer_key, invalid_offer_name, invalid_offer_stage, invalid_offer_status, message_template_body_too_long, message_template_empty_body, message_template_empty_subject, message_template_required_variables_missing, message_template_subject_too_long, message_template_unknown_variables, message_template_variable_too_long, outcome_connector_required, outcome_predates_prospecting_job, outcome_source_mismatch, professional_network_audience_source_unavailable, professional_network_member_prerequisites_missing, professional_network_members_unavailable, professional_network_selection_empty, prospect_research_audience_source_unavailable, prospect_research_member_prerequisites_missing, prospect_research_members_unavailable, prospect_research_selection_empty, prospecting_result_too_large, synthetic_prospect, synthetic_prospecting_result.

  • Audiences backend failures (502, bounded retry for safe reads): audiences_backend_generation_failed, audiences_backend_timeout.

Safe retries#

  • GET operations are read-only and may be retried when the code is transient.
  • rate_limit_exceeded includes Retry-After; the other 429 codes require a state or configuration change. Every request made with a valid key counts against that key's rate limit, including requests the API then refuses (for example project_required, project_not_found, project_archived, or forbidden), and those responses carry the RateLimit-* headers too. Repeated requests with an unknown or revoked key from one address are also throttled with 429 rate_limit_exceeded.
  • Before a job-creation POST, generate and persist a non-sensitive Idempotency-Key of at most 255 characters. The key is scoped to the authenticated project and operation.
  • If the connection is lost or the response is ambiguous, repeat the exact operation, input, and key. Matching retries within 24 hours return the original response without creating or billing another job.
  • idempotency_key_reused means the input differs from the original request. Use the exact original input or a new key. idempotency_in_progress means the first matching request has not stored its response yet; retry the same request after a short delay.
  • After 24 hours, the same key can create new work. Persist the returned job ID and do not use idempotency as long-term job storage.
  • Set retry and total-operation limits. Jitter prevents synchronized clients from retrying together.
const retryAfter = Number(response.headers.get("Retry-After") ?? "1");
if (response.status === 429 && body.error?.code === "rate_limit_exceeded") {
  await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
}

See Jobs and resumable polling for client deadlines and Limits, budgets, and usage for the three distinct 429 cases.