Surfer API Troubleshooting

Here is a list of possible issues or errors you might come across when using the Surfer API:

1. Request results in a generic HTML response

The URL you specified in the request is invalid and does not correspond to an API endpoint.

2. Any request results in a 401 Unauthorized with the "Access denied." message

The specified API key is incorrect, missing, or your plan doesn't support making API requests.

Please remember that the header "Key" has to be explicitly named "API-KEY".

3. Any request results in a 403 Forbidden with the "Access denied." message

Your current plan doesn’t support API. Please check your current subscription plan in the app settings and compare it to available plans with API on our pricing page.

4. POST requests result in 422 Unprocessable Entity with "Quota exceeded" message

• Audit and Content Editor:

This means you have no credits left for that particular tool in your current billing period.

If you have overage-capable plan like Lite or Max - you can still run Editor queries via overage system, but only via GUI.

• SERP Analyzer:

You exceeded your daily quota (100 queries/day by default). You can either wait or reach out to our Sales team to extend the limits with a custom Enterprise plan.

5. POST requests result in 400 Bad Request with "Internal server error" message

Your request contains a syntax error, for example, a missing comma.

6. POST requests result in 422 Unprocessable Entity with JSON message

Your request most likely doesn't contain the required parameters (such as missing keywords), or the query is malformed (a string was provided instead of an Array).

7. GET CE content requests result in 500 Internal Server Error

This means the query has no content stored. Most likely, it is an empty query that has never been visited via the app.

8. GET SERP Analyzer search_results requests result in 404 Not found with "Not found." message

The ID you specified in the URL of your request is incorrect, or this ID does not belong to the account associated with that API key.

9. GET SERP Analyzer search_results requests result in 200 OK, but most or some rows contain empty Strings

This means that the query did not complete all necessary calculations.

You can reference the 3rd column, "state," to see the state of each competitor crawl.

Similarly to regular queries:

• "completed" - crawl went through successfully, present data is based on content we were served with (doesn't contain empty values, default value is "0")

• "scheduled" - crawl is still processing (contains empty Strings)

• "failed" - crawl finished unsuccessfully - most likely we were either blocked, or we timed out while trying to access that URL (contains empty Strings)

10. GET SERP Analyzer prominent_terms requests result in 404 Not found with the "Not found" message

The ID you specified in the URL of your request is incorrect, or this ID does not belong to the account associated with that API key.

If you are sure that the ID is correct, then either:

• This query is still processing (listed as "scheduled" by exports/csv/serp_analyzer endpoint)

or

• We were not able to find any prominent phrases for that particular query, most likely due to a lack of sufficient written content within SERP competitors.

Additional resources:

Surfer API Introduction

Surfer API Documentation

Surfer API Examples of Use