API Response Codes & Rate Limits

HTTP Status Codes

Error Response Shape

{
  "error": "validation_failed",
  "message": "One or more fields failed validation",
  "field_errors": [
    { "field": "phone", "code": "invalid_format", "message": "Phone must be 10-15 digits" },
    { "field": "case_type", "code": "required", "message": "case_type is required for this campaign" }
  ]
}

Rate Limits

When you hit the limit, Lead Distro AI returns 429 with a `retry_after` header (seconds) and a `Retry-After` HTTP header per RFC 7231. Implement exponential backoff in your integration.

Exponential Backoff Recipe (Node.js)

async function postLeadWithBackoff(payload, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch('https://app.leaddistro.ai/api/v1/ingest', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': process.env.LEADDISTRO_API_KEY,
      },
      body: JSON.stringify(payload),
    });
    if (res.status !== 429 && res.status !== 503) return res;
    const retryAfter = Number(res.headers.get('retry-after')) || 2 ** attempt;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  }
  throw new Error('Max retries exceeded');
}