Errors & Rate Limits

This page provides a detailed reference for API error responses, rate limiting, IP allowlisting, and pagination. For a general overview of the API, see API Overview.

Error Response Format

All API errors return a consistent JSON structure with an error object:

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description of the error.",
    "param": "field_name",
    "request_id": "req_abc123def456"
  }
}

Error Object Fields

Error Codes Reference

Error Response Examples

401 Unauthorized

Returned when the API key is missing, invalid, expired, or revoked.

curl https://api.lostchurn.com/v1/payments \
  -H "Authorization: Bearer lc_live_invalid_key"

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "request_id": "req_1a2b3c4d5e6f"
  }
}

Common causes:

• API key was revoked from Settings > API Keys
• Key rotation grace period (24 hours) has expired for the old key
• Typo in the API key string
• Using a test key (lc_test_*) against production data or vice versa

403 Forbidden

Returned when the API key is valid but lacks permission for the requested operation.

# Using a read-only key to trigger a retry
curl -X POST https://api.lostchurn.com/v1/payments/pay_abc123/retry \
  -H "Authorization: Bearer lc_live_readonly_key"

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the 'write' scope required for POST /v1/payments/:id/retry.",
    "request_id": "req_7g8h9i0j1k2l"
  }
}

Common causes:

• API key was created with limited scopes (e.g., read only)
• Attempting admin operations with a non-admin key
• Trial expired -- write endpoints return trial_expired until you upgrade

429 Too Many Requests

Returned when the rate limit is exceeded.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 32 seconds.",
    "retry_after": 32
  }
}

The response includes a retry_after field (in seconds) and the following headers:

Rate Limiting

API requests are rate-limited per merchant (identified by API key). The rate limit window is a sliding 60-second window.

Limits by Plan

Rate Limit Headers

Every API response includes rate limit headers, even successful responses:

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1710000060

Best Practices for Rate Limits

IP Allowlisting

For additional security, you can restrict API access to specific IP addresses or CIDR ranges. When an IP allowlist is configured, requests from unlisted IPs are rejected with a 403 response.

Configuring IP Allowlisting

1. Go to Settings > API Keys > IP Allowlist.
2. Click Add IP Address.
3. Enter an IPv4 address (e.g., 203.0.113.42) or CIDR range (e.g., 203.0.113.0/24).
4. Click Save.

IP Allowlist Behavior

Pagination

All list endpoints return paginated results. LostChurn uses page-based pagination.

Query Parameters

Pagination Response

Every list response includes a pagination object:

{
  "data": [ ... ],
  "pagination": {
    "total": 1423,
    "page": 3,
    "per_page": 20,
    "total_pages": 72
  }
}

Pagination Example

# Fetch page 3 with 50 results per page
curl "https://api.lostchurn.com/v1/payments?page=3&per_page=50&status=pending" \
  -H "Authorization: Bearer lc_live_your_api_key"

Iterating Through All Pages

async function fetchAllPayments(apiKey) {
  let page = 1;
  let allPayments = [];

  while (true) {
    const response = await fetch(
      `https://api.lostchurn.com/v1/payments?page=${page}&per_page=100`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    const { data, pagination } = await response.json();

    allPayments = allPayments.concat(data);

    if (page >= pagination.total_pages) break;
    page++;
  }

  return allPayments;
}

Key Endpoint Quick Reference

For full documentation of each endpoint, see the dedicated API reference pages.

Payments

Customers

Campaigns

Analytics

Webhooks

Authentication

Authentication Quick Reference

All API requests require a Bearer token in the Authorization header:

curl https://api.lostchurn.com/v1/payments \
  -H "Authorization: Bearer lc_live_your_api_key"

Key Prefixes

For complete authentication documentation including key generation, scopes, and rotation, see Authentication.

Next Steps

• API Overview -- base URL, request format, and versioning
• Authentication -- API key management, scopes, and rotation
• Payments API -- query and retry failed payments
• Analytics API -- recovery and campaign performance metrics
• Webhooks -- outbound webhook events and signature verification