Error Handling

Best practices for handling API errors

Error Handling Guide

Learn how to properly handle errors from the GTMAPIs validation API.

Error Response Format

All errors return an appropriate HTTP status code with JSON body:

{
  "error": "Human-readable description",
  "code": "machine_readable_code"
}

Branch on code when it is present; error is written for people and may be clarified over time. Official clients preserve server-provided codes and fall back to a stable status-derived code when an older response does not include one.

Request Correlation

Every application response documented in OpenAPI includes an opaque X-Request-ID header. Preserve the ID from the terminal response and include it in support reports so the server-side trace can be located. Do not reuse an ID from an earlier retry when the final attempt fails before receiving an HTTP response; that network-only failure has no server-authored request ID.

Official SDK errors, CLI errors, and MCP structured errors expose the sanitized identifier directly. It is diagnostic metadata only and never affects whether an address is valid, chargeable, suppressed, or safe to send.

HTTP Status Codes

Status	Error	Description
200	Success	Request processed successfully
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Missing or invalid API key
402	Payment Required	Insufficient validation credits
403	Forbidden	Missing API-key scope, product access, or entitlement
409	Conflict	Idempotency key conflict or request still in progress
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error
502	Bad Gateway	Validation upstream failed; retry with backoff
503	Service Unavailable	Service temporarily unavailable

For example, a validation request that cannot reserve credits returns code: "insufficient_credits"; a temporary validation dependency failure returns code: "validation_upstream_failed".

When present, required is the reservation needed for the request and available is the balance observed by the API. Official SDKs, the CLI, and MCP preserve both fields; treat available as optional because older and synchronous responses may omit it.

Official SDKs, the CLI, and the local MCP package automatically attach idempotency keys to single validation, synchronous bulk, and asynchronous job writes. Supply a durable caller key when the same logical request may be retried after a process restart or across agent turns. Reuse it only with the identical request body; changed semantics return idempotency_key_conflict.

Clients retry network/timeouts, idempotency_request_in_progress, rate limits, and 5xx responses with bounded attempt budgets while preserving request identity. They do not retry bad input, authentication, insufficient credits, forbidden access, changed-body idempotency conflicts, or control_plane_route_misconfigured. The last code needs operator repair, so an automatic retry cannot make progress. Unknown future 5xx codes keep the status-based retry fallback.

Email Validation Codes

Every error from POST /v1/validate, POST /v1/validate/bulk, and POST /v1/validate/batch carries a stable code. Use these codes to decide whether to repair the request, split it, preserve its idempotency key, or retry:

Code	Status	What to do
invalid_json	400	Send a non-empty JSON object
payload_too_large	413	Reduce the request body or use the async batch route
invalid_email_field	400	Send email as a string
invalid_contact_context	400	Send first_name and last_name together as strings of 1–100 characters
invalid_force_refresh	400	Send force_refresh as a boolean
invalid_smtp_route_attestation	400	Send a configured route ID with 1–32 lowercase letters, digits, underscores, or hyphens
invalid_emails_field	400	Send a non-empty emails array
invalid_email_element	400	Remove or replace non-string members of a synchronous bulk request
too_many_emails	400	Split at maximum; provided reports the submitted count
no_valid_emails	400	Add at least one supported email string to the async batch
invalid_webhook_url	400	Use a public HTTP or HTTPS webhook URL
unsupported_benchmark_receipt_version	400	Use the returned supported_version
invalid_idempotency_key	400	Replace the malformed key
idempotency_key_conflict	409	Use a new key for the changed request
idempotency_request_in_progress	409	Retry the identical request after Retry-After with the same key
insufficient_credits	402	Add credits; inspect required and optional available
validation_upstream_failed	502	Retry with bounded backoff and the same idempotency key
batch_creation_failed	5xx	Retry async batch creation with the same idempotency key
benchmark_receipt_signing_unavailable	503	Retry later if a signed benchmark receipt is required
benchmark_receipt_signing_failed	503	Retry later with the same request identity
idempotency_unavailable	503	Retry later with the same key
idempotency_completion_failed	503	Retry the same request and key; do not create a replacement operation
internal_error	500	Retry with bounded backoff

An email string with invalid syntax is not a request-shape error. It remains a successful validation response with result: "invalid", so bulk callers keep one result per submitted string.

Signed CSV Write Codes

The signed-upload preparation and processing-start routes use these additional codes. Preserve the same idempotency key when the action says to retry:

Code	Status	What to do
invalid_filename	400	Send a non-empty CSV filename
invalid_content_sha256	400	Send a lowercase 64-character SHA-256 digest or omit the field
missing_batch_id	400	Send the batch ID returned by prepare-upload
missing_email_column	400	Send the CSV email column name or zero-based index
invalid_column_reference	400	Repair the column named by field
incomplete_contact_columns	400	Send both contact-name columns or omit both
invalid_job_state	400/409	Inspect the current job state; upload start requires uploading, while recovery requires completed
upload_prepare_failed	500	Retry upload preparation with bounded backoff and the same key
processing_start_failed	500	Retry processing start with bounded backoff and the same key

Catch-All Recovery Codes

Recovery start also uses job_not_found, invalid_job_state, and insufficient_credits. Its read and operational failures add these codes:

Code	Status	What to do
recovery_not_found	404	Stop polling or run recovery first; the source job may still exist
recovery_start_failed	404/5xx	Retry recovery start with bounded backoff
recovery_lookup_failed	500	Retry the recovery lookup with bounded backoff

Asynchronous Job Read Codes

The list, detail, and download routes use these additional codes:

Code	Status	What to do
invalid_page	400	Send an integer page greater than or equal to 1
invalid_limit	400	Send an integer limit from 1 through 100
invalid_job_status	400	Use a documented validation job status
invalid_download_type	400	Use results or original
unsupported_download_mode	400	Use mode=url
job_not_ready	400	Keep polling the job; download after it reaches completed
job_not_found	404	Stop polling and confirm the job ID and account
job_file_not_available	404	The job exists but the selected stored file is unavailable
job_list_failed	500	Retry listing with bounded backoff
job_lookup_failed	500	Retry the job lookup with bounded backoff
job_delete_failed	500	Confirm job state before retrying deletion
download_url_failed	500	Retry signed-URL creation with bounded backoff

Email Outcome Codes

Outcome import reuses invalid_json and payload_too_large. Import, report, and EmailBison connector routes use these additional codes:

Code	Status	What to do
invalid_csv	400	Repair the CSV syntax and headers
missing_outcomes	400	Send at least one outcome object or CSV data row
too_many_outcomes	400	Split the import; received reports the submitted count
invalid_report_timestamp	400	Send ISO-8601 start and end timestamps
invalid_report_range	400	Make start earlier than end
report_range_too_large	400	Reduce the report window to 366 days or less
connector_unavailable	404	Stop retrying and confirm that the account can use the connector
outcome_import_failed	500	Retry the same idempotent outcome import with bounded backoff
outcome_suppression_failed	500	Retry the same import; hard-bounce suppression did not complete
outcome_report_failed	500	Retry the aggregate report with bounded backoff
connector_status_failed	500	Retry connector status lookup with bounded backoff
connector_create_failed	500	Retry connector creation; replace any prior one-time URL only after success
connector_revoke_failed	500	Treat the connector as active and retry revocation

Recovery Feedback Codes

The gated catch-all recovery feedback import reuses invalid_json, payload_too_large, missing_outcomes, and too_many_outcomes.

Code	Status	What to do
recovery_feedback_import_failed	500	Retry the same append-only outcomes with their original external identities

Credit Balance Codes

Code	Status	What to do
credit_balance_failed	500	Retry the balance read with bounded backoff; do not assume a zero balance

API Gateway Codes

The public gateway uses these codes when it cannot reach the Product Control Plane. Preserve the request’s idempotency key for a retryable write.

Code	Status	What to do
control_plane_unavailable	503	Retry later with bounded backoff
control_plane_request_failed	502	Retry with bounded backoff and the same idempotency key
control_plane_timeout	504	Retry with bounded backoff and the same idempotency key
control_plane_route_misconfigured	502	Stop automatic retries and report the X-Request-ID to support

Authentication and Access Codes

Every rejection from the shared gates — API key, scope, subscription, product availability, rate limit — carries a code. Each one has a different fix, so branch on the code rather than on the status alone:

Code	Status	What happened	What to do
missing_api_key	401	No X-API-Key header	Send the header
invalid_api_key_format	401	Key does not start with gtm_test_ or gtm_live_	Check for a truncated or wrong-variable key
invalid_api_key	401	Key is well-formed but unknown	Confirm the key and the environment it belongs to
api_key_expired	401	Key passed its expiry	Rotate to a new key; safe to automate
api_key_inactive	401	Key was deactivated	Re-enable it in the dashboard
api_key_revoked	401	Key was revoked permanently	Issue a new key; do not retry with this one
api_key_owner_not_found	401	Key’s owning account is gone	Contact support
missing_scope	403	Key lacks the scope the endpoint needs (required_scope names it)	Grant the scope or use a key that has it
subscription_required	402	No active subscription	Start or restore a plan
product_unavailable	403	Endpoint is not publicly available yet	Use a generally available endpoint
rate_limit_exceeded	429	Throttled	Wait Retry-After seconds, then retry

api_key_expired, api_key_inactive, and api_key_revoked are deliberately separate codes even where the human-readable error string is the same, because expiry is routine rotation, deactivation is reversible, and revocation is not. That distinction is only available in code.

Codes are append-only. A code that exists keeps its meaning; a condition that later needs its own code gets a new one, so a switch you wrote today keeps matching everything it already handles.

switch (body.code) {
  case 'api_key_expired':
    return await rotateKeyAndRetry();      // routine, automatable
  case 'api_key_revoked':
  case 'api_key_inactive':
    return alertOperator(body.code);       // needs a human
  case 'rate_limit_exceeded':
    return await retryAfter(response.headers.get('Retry-After'));
  default:
    throw new Error(`${response.status}: ${body.error}`);
}

Common Errors

400 Bad Request

Cause: Invalid request format or missing required fields

Missing Email Field

{
  "error": "email must be a string",
  "code": "invalid_email_field"
}

Solution: Include email field in request body

// ❌ Wrong
fetch('https://api.gtmapis.com/v1/validate', {
  body: JSON.stringify({})
});

// ✅ Correct
fetch('https://api.gtmapis.com/v1/validate', {
  body: JSON.stringify({ email: '[e-mail]' })
});

Invalid Email Syntax

{
  "email": "not-an-email",
  "result": "invalid",
  "syntax_valid": false,
  "send_recommendation": "do_not_send",
  "pre_send_bounce_risk": "blocked",
  "credits_charged": 0
}

Solution: Treat this HTTP 200 response as a completed validation. Do not retry or send to the address. Client-side format checks can improve form feedback, but the API result remains the validation source of truth.

Too Many Emails in Bulk Request

{
  "error": "Maximum 100 emails per request. Received: 150",
  "code": "too_many_emails",
  "maximum": 100,
  "provided": 150
}

Solution: Split into batches of 100

function chunkArray(array, size) {
  const chunks = [];
  for (let i = 0; i < array.length; i += size) {
    chunks.push(array.slice(i, i + size));
  }
  return chunks;
}

const batches = chunkArray(emails, 100);
for (const batch of batches) {
  await validateBulk(batch);
}

401 Unauthorized

Cause: Missing or invalid API key

Missing API Key Header

{
  "error": "Unauthorized",
  "message": "X-API-Key header is required"
}

Solution: Always include X-API-Key header

// ❌ Wrong
fetch('https://api.gtmapis.com/v1/validate', {
  headers: {
    'Content-Type': 'application/json'
  }
});

// ✅ Correct
fetch('https://api.gtmapis.com/v1/validate', {
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.GTMAPIS_API_KEY
  }
});

Invalid API Key

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Solution: Verify API key format and validity

// Check API key format
if (!apiKey || !apiKey.match(/^gtm_(test|live)_[a-f0-9]{32}$/)) {
  throw new Error('Invalid API key format');
}

Revoked API Key

{
  "error": "Unauthorized",
  "message": "API key has been revoked"
}

Solution: Generate a new API key from the dashboard

403 Forbidden

When a key lacks permission, the API returns the exact scope needed for the endpoint:

{
  "error": "API key is missing required scope: email:validate:single",
  "code": "missing_scope",
  "required_scope": "email:validate:single"
}

Do not retry this response with the same key. Add required_scope to the key, or rotate to a least-privilege key that includes it, and then retry. Branch on code; do not parse the human-readable error string.

Other product or entitlement gates can also return 403 without required_scope. Treat those as non-retryable access failures and preserve the human-readable error for the operator.

429 Too Many Requests

Cause: Rate limit exceeded (10,000 requests/minute per API key or 1,000 requests/minute per IP)

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 10000 requests per minute",
  "retry_after": 60
}

Solution: Implement retry logic with exponential backoff

async function validateWithRetry(email, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.gtmapis.com/v1/validate', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': process.env.GTMAPIS_API_KEY
        },
        body: JSON.stringify({ email })
      });

      if (response.status === 429) {
        const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
        console.log(`Rate limited. Waiting ${retryAfter}s...`);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries) throw error;

      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

500 Internal Server Error

Cause: Unexpected server error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Solution: Retry request or contact support

async function validateWithErrorHandling(email) {
  try {
    return await validateEmail(email);
  } catch (error) {
    if (error.status === 500) {
      // Log for investigation
      console.error('Server error:', error);

      // Retry once after delay
      await new Promise(resolve => setTimeout(resolve, 5000));
      return await validateEmail(email);
    }
    throw error;
  }
}

503 Service Unavailable

Cause: Service temporarily unavailable (maintenance or overload)

{
  "error": "Service Unavailable",
  "message": "Service temporarily unavailable. Please try again later."
}

Solution: Implement circuit breaker pattern

class CircuitBreaker {
  constructor(threshold = 5, timeout = 60000) {
    this.failureCount = 0;
    this.threshold = threshold;
    this.timeout = timeout;
    this.state = 'CLOSED';  // CLOSED, OPEN, HALF_OPEN
    this.nextAttempt = Date.now();
  }

  async execute(fn) {
    if (this.state === 'OPEN') {
      if (Date.now() < this.nextAttempt) {
        throw new Error('Circuit breaker is OPEN');
      }
      this.state = 'HALF_OPEN';
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  onSuccess() {
    this.failureCount = 0;
    this.state = 'CLOSED';
  }

  onFailure() {
    this.failureCount++;
    if (this.failureCount >= this.threshold) {
      this.state = 'OPEN';
      this.nextAttempt = Date.now() + this.timeout;
    }
  }
}

// Usage
const breaker = new CircuitBreaker();

async function validateWithCircuitBreaker(email) {
  return await breaker.execute(() => validateEmail(email));
}

Validation Result Errors

Even with HTTP 200, emails can have validation issues:

Invalid Email

{
  "email": "[e-mail]",
  "result": "invalid",
  "reason": "Domain has no MX records",
  "validation_layer": "dns"
}

Handling:

if (result.result === 'invalid') {
  console.log(`Email ${result.email} is invalid: ${result.reason}`);
  // Remove from list
  removeFromList(result.email);
}

Risky Email

{
  "email": "[e-mail]",
  "result": "risky",
  "reason": "Catch-all domain detected"
}

Handling:

if (result.result === 'risky') {
  console.log(`Email ${result.email} is risky: ${result.reason}`);
  // Mark as low priority or exclude
  markAsLowPriority(result.email);
}

Unknown Verification

{
  "email": "[e-mail]",
  "result": "unknown",
  "reason": "SMTP verification not permitted"
}

Handling:

if (result.result === 'unknown') {
  console.log(`Cannot verify ${result.email}: ${result.reason}`);
  // Test with small batch first
  addToTestBatch(result.email);
}

Error Handling Patterns

Comprehensive Error Handler

async function validateEmailSafely(email) {
  try {
    const response = await fetch('https://api.gtmapis.com/v1/validate', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.GTMAPIS_API_KEY
      },
      body: JSON.stringify({ email })
    });

    // Handle HTTP errors
    if (!response.ok) {
      switch (response.status) {
        case 400:
          throw new Error('Invalid request format');
        case 401:
          throw new Error('Invalid API key - check your credentials');
        case 429:
          const retryAfter = response.headers.get('Retry-After') || 60;
          throw new Error(`Rate limited - retry after ${retryAfter}s`);
        case 500:
          throw new Error('Server error - please retry');
        case 503:
          throw new Error('Service unavailable - try again later');
        default:
          throw new Error(`HTTP ${response.status}`);
      }
    }

    const result = await response.json();

    // Handle validation results
    switch (result.result) {
      case 'valid':
        return { status: 'success', data: result };

      case 'valid_role_based':
        return {
          status: 'warning',
          message: 'Role-based email (info@, support@)',
          data: result
        };

      case 'risky':
        return {
          status: 'warning',
          message: 'Catch-all domain - cannot verify mailbox',
          data: result
        };

      case 'invalid':
        return {
          status: 'error',
          message: result.reason || 'Invalid email',
          data: result
        };

      case 'unknown':
        return {
          status: 'warning',
          message: 'Cannot verify - server restrictions',
          data: result
        };

      default:
        return {
          status: 'error',
          message: 'Unexpected result type',
          data: result
        };
    }
  } catch (error) {
    // Network or parsing errors
    console.error('Validation error:', error);
    return {
      status: 'error',
      message: error.message,
      data: null
    };
  }
}

// Usage
const result = await validateEmailSafely('[e-mail]');

if (result.status === 'success') {
  // Email is valid
  console.log('Valid email:', result.data.email);
} else if (result.status === 'warning') {
  // Email has issues but may be usable
  console.warn(result.message, result.data);
} else {
  // Email is invalid or error occurred
  console.error(result.message);
}

Bulk Validation Error Handling

async function validateBulkWithErrorHandling(emails) {
  const results = [];
  const errors = [];

  for (let i = 0; i < emails.length; i += 100) {
    const batch = emails.slice(i, i + 100);

    try {
      const response = await fetch('https://api.gtmapis.com/v1/validate/bulk', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': process.env.GTMAPIS_API_KEY
        },
        body: JSON.stringify({ emails: batch })
      });

      if (!response.ok) {
        // Log error but continue with next batch
        errors.push({
          batch: i / 100 + 1,
          emails: batch,
          error: `HTTP ${response.status}`
        });
        continue;
      }

      const batchResults = await response.json();
      results.push(...batchResults.results);

    } catch (error) {
      // Network error - log and continue
      errors.push({
        batch: i / 100 + 1,
        emails: batch,
        error: error.message
      });
    }

    // Rate limit delay
    await new Promise(resolve => setTimeout(resolve, 500));
  }

  return {
    results,
    errors,
    summary: {
      total: emails.length,
      validated: results.length,
      failed: errors.reduce((sum, e) => sum + e.emails.length, 0)
    }
  };
}

Monitoring and Logging

Log Errors for Analysis

function logValidationError(error, context) {
  console.error('Validation Error:', {
    timestamp: new Date().toISOString(),
    error: error.message,
    stack: error.stack,
    context: {
      email: context.email,
      apiKey: context.apiKey?.substring(0, 15) + '...',  // Partial key only
      endpoint: context.endpoint
    }
  });

  // Send to error tracking service
  if (process.env.SENTRY_DSN) {
    Sentry.captureException(error, {
      contexts: { validation: context }
    });
  }
}

Track Error Rates

class ErrorTracker {
  constructor() {
    this.errors = new Map();
  }

  track(errorType) {
    const count = this.errors.get(errorType) || 0;
    this.errors.set(errorType, count + 1);
  }

  getStats() {
    return Object.fromEntries(this.errors);
  }

  reset() {
    this.errors.clear();
  }
}

const errorTracker = new ErrorTracker();

// Track errors
try {
  await validateEmail(email);
} catch (error) {
  if (error.status === 429) {
    errorTracker.track('rate_limit');
  } else if (error.status === 500) {
    errorTracker.track('server_error');
  }
  throw error;
}

// Review stats periodically
setInterval(() => {
  console.log('Error stats:', errorTracker.getStats());
  errorTracker.reset();
}, 60000);

Next Steps

Rate Limits

Understand rate limiting strategies

API Integration

Full integration patterns