What error code does the API return when the key is revoked?

When you call any Valid Email Checker API endpoint with a key that has been disabled by you, deleted, or suspended by our abuse-protection system, the response is HTTP 403 Forbidden. The key was recognized — it exists in the database — but it is no longer authorized to make requests. The body explains which state the key is in so your client can react appropriately.

The exact response shape

{
  "error": "API key is suspended",
  "reason": "This API key has been suspended"
}

When you see 403 vs 401

The distinction matters because retry logic should treat the two cases differently:

How to handle 403 in client code

const response = await fetch(/* ... */);

if (response.status === 403) {
  const data = await response.json();
  if (data.error === 'API key is suspended') {
    // Do NOT retry — the key is no longer valid.
    // Alert the operator to investigate or rotate.
    alertOperator(`VEC key suspended: ${data.reason}`);
    haltIntegration();
    return;
  }
  if (data.error === 'Access denied') {
    // IP-level block — contact support if unexpected.
    alertOperator('VEC IP blocked');
    return;
  }
}

Critical: do not retry on a 403. Unlike 429 (rate-limited) where waiting fixes the problem, a 403 means the key state itself is wrong. Retries just generate noise in the api_requests log and may push the IP closer to abuse-protection thresholds. Surface the error to a human and stop the integration.

What about deleted keys?

Keys that you deleted from the Developer page are treated as if they never existed. The next request with that key returns 401 Invalid or inactive API key, not 403. The 403 path is reserved for keys whose row still exists in active or disabled state with is_suspended = true. See the difference between revoking and deleting for why those two states are not interchangeable.

Re-enabling a disabled key

If you disabled a key by accident, open the Developer page, click the three-dot menu on the row, and click Enable. The status flips back to active and the next request succeeds — no regeneration needed, the key value is unchanged. Admin-suspended keys cannot be re-enabled from the UI; you have to contact support to lift the suspension, since the underlying abuse signal needs to clear first.

In-flight behavior

Requests already past the auth gate when you revoke a key finish normally — the API does not abort mid-flight. Only the next request hits 403. See what happens to in-flight verifications when a key is revoked for the full picture, including bulk-task behavior.

Next steps