Error Codes

All errors in LightLead are classified by category. Each category has its own code range and a typical resolution template.

Error categories

Category	Codes	Description	Typical resolution
AUTH	1000–1999	Authorization and authentication errors	Reconnect the source, check permissions
THROTTLE	2000–2999	Rate limits exceeded	Wait, adjust the interval, upgrade the plan
PAYLOAD	3000–3999	Invalid request parameters	Check the report configuration
TRANSPORT	4000–4999	Network errors and timeouts	Check the connection, retry later
PERMISSION	5000–5999	Data access errors	Check permissions at the source
INTERNAL	9000–9999	Internal system errors	Contact support

AUTH (1000–1999) — Authorization errors

Code	Error	Cause	Solution
1001	invalid_token	The access token is invalid	Reconnect the source
1002	expired_token	The token has expired	Refresh the token or reconnect
1003	revoked_token	The token was revoked by the user or provider	Reauthorize via OAuth
1004	invalid_refresh_token	The refresh token is invalid	Full reauthorization
1005	missing_credentials	Credentials weren't provided	Check the connection configuration
1006	auth_server_unavailable	The authorization server is unavailable	Wait and retry
1010	account_suspended	The account at the source is blocked	Restore the account at the source

Message template:

Authorization error [AUTH-1002]: The token has expired.
Connection: Google Ads (ID: abc123)
Solution: click "Reconnect" in the source settings.

Typical resolution:

1. Go to the connection settings
2. Click "Reconnect" or "Refresh Token"
3. Go through OAuth authorization again

THROTTLE (2000–2999) — Rate limits exceeded

Code	Error	Cause	Solution
2001	rate_limit_exceeded	The source API's request limit was exceeded	Increase the interval between requests
2002	quota_exceeded	The daily/monthly API quota is exhausted	Wait for the quota to reset or upgrade the plan
2003	concurrent_limit	Too many concurrent requests	Wait for other reports to finish
2004	source_rate_limit	The source imposed a restriction	Wait, the system will retry automatically
2010	daily_limit_reached	The daily run limit was reached	Wait for the next day

Message template:

Limit exceeded [THROTTLE-2001]: The source API's request limit was exceeded.
Connection: TikTok Ads (ID: def456)
Limit: 100 requests/minute
Solution: the system will automatically retry the request in 60 seconds.

Typical resolution:

1. No action needed — the system automatically retries with exponential backoff
2. If the error recurs regularly — increase the schedule interval
3. Consider upgrading the plan to increase quotas

PAYLOAD (3000–3999) — Parameter errors

Code	Error	Cause	Solution
3001	invalid_field	A nonexistent field was specified	Check the field name
3002	incompatible_fields	Incompatible fields in a single report	Review the set of dimensions and metrics
3003	invalid_date_range	Invalid date range	Check start and end
3004	date_range_too_large	The date range is too large	Shorten the period
3005	invalid_filter	Invalid filter condition	Check the operator and value type
3006	too_many_dimensions	The number of dimensions was exceeded	Remove extra dimensions
3007	too_many_metrics	The number of metrics was exceeded	Remove extra metrics
3008	circular_dependency	A circular dependency in calculated metrics	Check your formulas

Message template:

Parameter error [PAYLOAD-3003]: Invalid date range.
Field: date_range
Value: start=2026-02-31
Solution: February 31st doesn't exist. Specify a valid date.

Typical resolution:

1. Check the report configuration
2. Fix the invalid parameters
3. Rerun the report

TRANSPORT (4000–4999) — Network errors

Code	Error	Cause	Solution
4001	connection_timeout	Timeout connecting to the source's API	Retry later
4002	read_timeout	Timeout reading the response	Retry later
4003	dns_error	DNS resolution error	Check the network connection
4004	ssl_error	SSL/TLS certificate error	Contact support
4005	connection_refused	The server refused the connection	Retry later
4006	http_5xx	The source's server returned a 5xx	Retry later
4007	response_too_large	The response exceeds the maximum size	Narrow the request

Message template:

Network error [TRANSPORT-4001]: Timeout connecting to the source's API.
Connection: Google Ads (ID: ghi789)
Solution: the system will automatically retry the request. If the error persists, check the source's status page.

Typical resolution:

1. The system makes up to 3 automatic retries
2. Check the source's status page
3. Retry manually later

PERMISSION (5000–5999) — Access errors

Code	Error	Cause	Solution
5001	access_denied	Access to the data was denied	Check permissions at the source
5002	insufficient_scope	Insufficient OAuth scopes	Reconnect with the required scopes
5003	account_not_found	The account wasn't found	Check the account ID
5004	field_not_accessible	No access to a specific field	Remove the field from the report
5005	workspace_access_denied	No access to the workspace	Request access from the owner

Message template:

Access error [PERMISSION-5001]: Access to the data was denied.
Connection: Facebook Ads (ID: jkl012)
Reason: the user doesn't have permission to read the ad account.
Solution: grant the user administrator or analyst rights in the ad account.

Typical resolution:

1. Check the user's permissions at the source
2. Grant the required permissions
3. Reconnect the source

INTERNAL (9000–9999) — Internal errors

Code	Error	Cause	Solution
9001	internal_error	An unknown internal error	Contact support
9002	data_pipeline_error	An error in the data processing pipeline	Contact support
9003	storage_error	A data storage error	Contact support
9004	serialization_error	A data serialization error	Check field types
9005	normalization_error	A data normalization error	Check the configuration
9999	unknown_error	An unknown error	Contact support

Message template:

Internal error [INTERNAL-9001]: An unknown internal error occurred.
Request ID: req_abc123def456
Solution: contact LightLead support and provide the request ID.

Typical resolution:

1. Copy the request ID
2. Contact support via chat or email
3. Provide the request ID, plan, and a description of the actions taken

Error response format

All errors are returned in a unified format:

{
  "error": {
    "category": "AUTH",
    "code": 1002,
    "message": "The token has expired",
    "details": {
      "connection_id": "abc123",
      "source_type": "google_ads",
      "token_expired_at": "2026-01-01T00:00:00Z"
    },
    "request_id": "req_abc123def456",
    "resolution": "Click \"Reconnect\" in the source settings"
  }
}

Related pages

• Report Statuses
• Connection Statuses
• Limits