Credits

How enrichment credits are charged and how to handle insufficient balance.

A small number of endpoints, the paid enrichment ones, consume credits. The credit middleware runs after authentication and rate-limit checks but before the enrichment provider is called:

If the workspace has unlimited credits or has been manually bypassed, the request proceeds.
Else if remaining credits < cost, the API returns 402 insufficient_credits without running the enrichment.
Otherwise the request proceeds; credits are deducted only on a successful result.

Charged endpoints

Endpoint	Cost	Charged when
`POST /enrich/email`	1 credit	Endpoint returns a non-empty `email`.
`POST /enrich/phone`	10 credits	Endpoint returns a non-empty `phone`.

If no email or phone is found, no credit is deducted. All other endpoints are free.

Insufficient credits response

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient enrichment credits. 1 credit required for POST /api/v1/enrich/email, 0 remaining.",
    "details": { "endpoint": "POST /api/v1/enrich/email", "credits_required": 1, "credits_remaining": 0 }
  }
}

details.credits_required and details.credits_remaining are always present on this error so you can surface a precise top-up prompt to your users.

Checking your balance

Call GET /account/credit-usage any time.

Workspaces with unlimited or manually bypassed quotas return credits.unlimited: true or credits.bypassed: true. Treat those as unlimited and do not block usage on credit count.