Meta/Facebook extract failures: unexpected HTML response

Introduction

Meta/Facebook extract failures can happen when the Facebook API returns a response that the connector does not expect. In Kleene, the connector expects a valid JSON response from the API. If the API returns HTML instead, the extract can fail while trying to parse the response.

Issue description

A Meta/Facebook extract failed with an error similar to:

Unexpected character ('<' (code 60)): expected a valid value (JSON ...)

This means the connector attempted to parse the API response as JSON, but the first character in the response was <. Since < usually indicates the start of an HTML document, the response was not valid JSON.

Signs

You may be dealing with this issue if a Facebook or Meta extract fails with a JSON parsing error that references character < or code 60. The failure may happen even if the connector configuration is correct.

This type of error is often caused by a temporary API response, network issue, rate limit page, service interruption, or an unexpected HTML error page returned by Meta/Facebook instead of the expected JSON payload.

Basic troubleshooting steps

Start with the following checks to narrow down the cause of the error:

• Review the full extract error and confirm whether it mentions Unexpected character ('<' (code 60)).
• Check whether the failure happened once or is repeating across multiple runs.
• Re-run the extract or wait for the next scheduled run to confirm whether the issue resolves by itself.
• Check whether Meta/Facebook API availability or rate limiting may have affected the request.
• Confirm that the connector authentication is still valid if the issue repeats.
• Review any API response details available in the logs.
• Escalate if the API continues returning HTML instead of JSON.

Common causes and how to fix them

Unexpected HTML response from Facebook

The connector expects JSON, but the Facebook API returned HTML. This can happen if the API temporarily returns an error page, maintenance page, login page, throttling response, or other non-JSON content.

How to fix it: if the issue happened once and the next scheduled run succeeded, no connector-side fix is required. Treat it as a transient API or network response.

Temporary API or network issue

Short-lived API interruptions can cause a single extract run to fail while later runs succeed. The connector may receive an incomplete, redirected, or unexpected response during the interruption.

How to fix it: re-run the extract or allow the next scheduled run to complete. If the next run succeeds, monitor for recurrence rather than changing connector configuration immediately.

Rate limiting or throttling

Meta/Facebook may return an unexpected response when requests are throttled or rate limited. Depending on the response format, this can appear as a parsing error rather than a clear rate-limit message.

How to fix it: check whether failures repeat at similar times or under high request volume. If they do, investigate API rate limits, scheduling, and request volume.

Authentication or permission issue

If authentication expires or permissions change, the API may return an unexpected page or response instead of the expected JSON data.

How to fix it: if failures repeat, verify the connector authentication, token status, and required Meta/Facebook permissions. Reconnect or refresh credentials if required.

Practical troubleshooting workflow

1. Read the extract error and confirm it references Unexpected character ('<' (code 60)).
2. Check whether the response appears to be HTML rather than JSON.
3. Confirm whether the failure occurred once or across repeated runs.
4. If it happened once, re-run the extract or wait for the next scheduled run.
5. If the next run succeeds, treat the issue as transient and no connector-side fix is needed.
6. If the error repeats, check Meta/Facebook API availability and rate limiting.
7. Verify connector authentication and permissions.
8. Review logs for the response body or status code if available.
9. Escalate with examples if Meta/Facebook continues returning non-JSON responses.

Best practices to avoid repeated Meta/Facebook extract failures

• Monitor whether code 60 errors are isolated or recurring.
• Avoid changing connector configuration after a single transient failure if the next run succeeds.
• Check API status and rate limits when failures happen repeatedly.
• Keep connector authentication current and refresh credentials when needed.
• Capture example timestamps and error messages before escalating recurring issues.
• Review logs for HTTP status codes or response snippets when available.
• Treat HTML responses from an API as a sign that the connector did not receive the expected JSON payload.

Additional information

For this issue, the Facebook API returned an unexpected HTML response starting with < instead of the expected JSON payload. The next scheduled run succeeded, so no connector-side fix was required.

If the error repeats, investigate Facebook API availability, authentication, throttling, or any response details available in the extract logs.