The Email Validation API uses a credit-based billing system.
Each email validation consumes credits, whether processed individually or in bulk.
You can check your current balance, track usage, and handle low-credit scenarios using the Credits API.

This section explains how credits work, how they are consumed, and how to retrieve credit information programmatically.

1. Endpoint

GET /api/v1/credits/balance

Returns a detailed breakdown of your remaining credits and usage.

Authentication (Required)

Authorization: Bearer YOUR_API_KEY

2. Example Request

curl https://rapid-email-verifier.fly.dev/api/v1/credits/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

3. Success Response

Example (200 OK)

{
  "success": true,
  "data": {
    "user_id": "e5acee5c-87bd-40cc-a650-8a8462e4f14b",
    "available_credits": 175,
    "used_credits": 25,
    "free_credits": 0,
    "subscription_credits": 100,
    "purchased_credits": 50,
    "bonus_credits": 25,
    "reserved_credits": 0
  },
  "message": "Credit balance retrieved successfully",
  "metadata": {
    "request_id": "550e8400-e29b-41d4-a716-446655440004",
    "processing_time_ms": 15,
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "1.0.0"
  }
}

4. Credit Breakdown (Explained)

5. Credit Consumption Rules

Single Email Validation

• Consumes: 1 credit / email

Bulk Validation

• Consumes: 1 credit / email submitted

Failed or Invalid Emails

• Still consume credits

• Exception: Certain internal system errors may auto-refund (rare)

Job Failure

• Credits for already processed emails remain consumed

• Remaining unprocessed emails may not consume credits (depends on failure type)

6. Low Credits & Out-of-Credits Behavior

When credits run out, the API returns:

402 — Insufficient Credits

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits. Please purchase more credits to continue."
  }
}

Clients should:

• Halt large jobs

• Notify the user

• Prompt for purchasing more credits

7. Billing Models Supported

Your platform currently supports:

1. Subscription (Upcoming)

• Credits added at the start of each billing cycle

• Expire at the end of cycle (plan-specific)

2. Pay-As-You-Go (One-Time Credit Packs)

• Credits never expire (unless marked as promotional)

• Purchased through Stripe or other payment gateway

3. Bonus / Promo Credits

• Expire in 30 days (if specified)

• Used only after subscription & purchased credits are exhausted

8. Credit Best Practices

• Fetch credit balance periodically to avoid job interruptions

• Display credit warnings at thresholds (e.g., <50 credits)

• Add "auto-recharge" option for users with recurring workloads

• Reserve credits for large bulk jobs so they cannot be accidentally overspent

• Track usage per user (in multi-tenant systems)

9. Error Responses

401 — Unauthorized

Missing/invalid API key:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}

429 — Rate Limit Exceeded

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Try again later."
  }
}