Error Codes

All errors follow a consistent JSON structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {}
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Authentication Errors (401)

MISSING_API_KEY

No API key provided in the request.

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Provide via X-API-Key header, Authorization: Bearer token, or api_key query parameter."
  }
}

INVALID_API_KEY

The provided API key is malformed or doesn’t exist.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Resolution: Verify your API key starts with spm_live_ or spm_test_ and is 32+ characters.

API_KEY_DISABLED

The API key exists but has been disabled.

{
  "error": {
    "code": "API_KEY_DISABLED",
    "message": "This API key has been disabled"
  }
}

API_KEY_EXPIRED

The API key has passed its expiration date.

{
  "error": {
    "code": "API_KEY_EXPIRED",
    "message": "This API key has expired",
    "details": {
      "expiredAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

Authorization Errors (403)

INSUFFICIENT_SCOPE

The API key doesn’t have permission for this operation.

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "API key lacks required scope: validate:write",
    "details": {
      "requiredScope": "validate:write",
      "availableScopes": ["validate:read"]
    }
  }
}

IP_NOT_ALLOWED

Request came from an IP address not in the key’s allowlist.

{
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Request IP not in allowed list",
    "details": {
      "requestIp": "192.168.1.1"
    }
  }
}

FEATURE_NOT_AVAILABLE

The requested feature isn’t available on your plan.

{
  "error": {
    "code": "FEATURE_NOT_AVAILABLE",
    "message": "SMTP verification is not available on the Growth tier",
    "details": {
      "feature": "smtpVerification",
      "currentTier": "growth",
      "requiredTier": "business"
    }
  }
}

Validation Errors (400)

MISSING_EMAIL

{
  "error": {
    "code": "MISSING_EMAIL",
    "message": "Email parameter is required"
  }
}

INVALID_EMAIL

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Email must be a non-empty string"
  }
}

BATCH_TOO_LARGE

{
  "error": {
    "code": "BATCH_TOO_LARGE",
    "message": "Batch size exceeds maximum of 100 emails",
    "details": {
      "submitted": 150,
      "maximum": 100
    }
  }
}

BATCH_EMPTY

{
  "error": {
    "code": "BATCH_EMPTY",
    "message": "At least one email is required for batch validation"
  }
}

Rate Limit Errors (429)

RATE_LIMIT_EXCEEDED

Too many requests in the current time window.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. 100 requests per minute allowed.",
    "details": {
      "limit": 100,
      "window": "minute",
      "retryAfter": 45
    }
  }
}

DAILY_LIMIT_EXCEEDED

{
  "error": {
    "code": "DAILY_LIMIT_EXCEEDED",
    "message": "Daily limit of 10,000 requests exceeded",
    "details": {
      "limit": 10000,
      "used": 10000,
      "resetsAt": "2024-01-16T00:00:00.000Z"
    }
  }
}

QUOTA_EXCEEDED

Monthly quota exhausted (Free/Hobby tiers stop at 100%).

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota exceeded. Upgrade your plan for more validations.",
    "details": {
      "limit": 100,
      "used": 100,
      "percentage": 100,
      "tier": "free"
    }
  }
}

GRACE_PERIOD_EXCEEDED

Exceeded the 120% grace period (Growth+ tiers).

{
  "error": {
    "code": "GRACE_PERIOD_EXCEEDED",
    "message": "Exceeded 120% grace period. Hard stop until next billing cycle.",
    "details": {
      "limit": 10000,
      "used": 12001,
      "percentage": 120.01,
      "hardLimit": 12000,
      "resetsAt": "2024-02-01T00:00:00.000Z"
    }
  }
}

Server Errors (500)

INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

VALIDATION_TIMEOUT

{
  "error": {
    "code": "VALIDATION_TIMEOUT",
    "message": "Validation timed out after 30 seconds"
  }
}

Resolution: Try quickMode: true to skip slow checks.

SDK Error Handling

The official SDK provides typed error classes:

import {
  Spamidate,
  AuthenticationError,
  RateLimitError,
  QuotaExceededError,
  ValidationInputError,
  NetworkError,
  TimeoutError,
} from '@spamidate/sdk';

try {
  const result = await client.validate('user@example.com');
} catch (error) {
  if (error instanceof RateLimitError) {
    // Wait and retry
    await sleep(error.retryAfter * 1000);
    return client.validate(email);
  }

  if (error instanceof QuotaExceededError) {
    notifyAdmin('Quota exceeded - upgrade needed');
  }

  if (error instanceof AuthenticationError) {
    console.error('Check API key configuration');
  }
}

Retryable Errors

Error Code	Retryable	Action
`RATE_LIMIT_EXCEEDED`	Yes	Wait for `Retry-After`
`VALIDATION_TIMEOUT`	Yes	Retry with `quickMode: true`
`INTERNAL_ERROR`	Yes	Exponential backoff
`INVALID_API_KEY`	No	Fix API key
`QUOTA_EXCEEDED`	No	Upgrade plan