Errors and pagination

Start with the endpoint's response schema and the HTTP status code. Different endpoints can use different response shapes and pagination cursors.

Authentication errors

For a 401 response, check that you sent the X-API-Key header and that its value is a valid key for the intended company. Keep the key private when sharing logs or asking for support.

Request errors

For a 400 response, compare your request with the endpoint's required fields, enum values, and examples. For a 404, check the record ID and the company associated with your key.

Rate limits

The API rate limit is company-based. Plan for roughly one request per second and slow down when you receive 429. Contact LeadTruffle support if your integration needs a higher rate.

Before retrying a request that creates data or sends a message, check whether the first attempt took effect. A network timeout alone does not prove the operation failed.

Pagination

Follow the cursor documented on the specific endpoint. Do not assume every list operation uses the same parameters.

For List leads created:

Send the first request with your desired limit (up to 100).
Process the returned data.leads.
If data.hasMore is true, use the oldest returned lead's timestamp as the next request's before value.
Continue until data.hasMore is false. If a page is empty or its cursor does not advance, stop and investigate rather than repeating the same request indefinitely.

curl --get \
  --url 'https://pub-api.leadtruffle.com/api/v2/pub/leads-created' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'before=2026-01-01T00:00:00.000Z'

The date above is an example. Use the timestamp from your previous response.

Webhook issues

Confirm the subscription's URL and event type. If signature verification fails, check that you use the exact raw request body and the webhook's shared secret. Parsing and re-serializing JSON can change the bytes used for signing.

See Receive lead events and Verify webhook signatures.

Get help

Email support@leadtruffle.com with the endpoint, time of the request, HTTP status, and a redacted response. Do not include API keys or webhook secrets.