Errors and retries

All errors use the same envelope:

{
  "data": null,
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient enrichment credits.",
    "details": {
      "available": 250,
      "required": 400,
      "shortfall": 150
    }
  }
}

Branch on error.code, not the human-readable message.

HTTP	Code	Meaning	Retry guidance
400	`invalid_request`	The request body or cursor is invalid.	Fix the request.
401	`invalid_api_key`	The key is missing or invalid.	Replace the credential.
401	`revoked_api_key`	The key was revoked.	Create and deploy a new key.
402	`insufficient_credits`	Eligible accounts exceed available credits.	Add credits or submit fewer accounts.
404	`not_found`	The resource does not exist in this organization.	Check the ID; do not retry unchanged.
409	`campaign_not_enrichable`	The campaign cannot transition from its current state.	Inspect `details.status`.
409	`campaign_not_editable`	The campaign can only be updated while it is a `draft`.	Inspect `details.status`.
409	`enrichment_pending`	A launch is still converging.	Retry the same enrich call with backoff.
409	`results_not_ready`	Export was requested before enrichment completed.	Poll the campaign, then retry.
410	`results_expired`	The results access window ended.	Do not retry.
422	`no_eligible_accounts`	No input accounts can be enriched or exported.	Change the input or eligibility window.
429	`concurrency_limit_exceeded`	The organization has too many accounts in flight.	Wait for campaigns to finish, then retry.
500	`internal_error`	An unexpected error occurred.	Retry with exponential backoff and jitter.

For retryable requests, use capped exponential backoff with jitter. Preserve the same campaign ID when retrying campaigns/enrich; creating a new campaign creates a separate job.

Get started

Build with DataLane