Here is a list of possible issues or errors you might come across when using Surfer API:
Request results in a generic HTML response
Request results in a generic HTML response
The URL you specified within the request is invalid and is not used for an API endpoint.
Any request results in 401 Unauthorized with "Access denied." message
Any request results in 401 Unauthorized with "Access denied." message
The specified API key is incorrect, missing or your plan doesn't support making API requests.
Please remember that header "Key" has to be explicitly named "API-KEY".
Any request results in 403 Forbidden with "Access denied." message
Any request results in 403 Forbidden with "Access denied." message
Your current plan does not support API or you did not purchase the required API add-on.
POST requests result in 422 Unprocessable Entity with "Quota exceeded" message
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 Lite, Essential, 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.
POST requests result in 400 Bad Request with "Internal server error" message
POST requests result in 400 Bad Request with "Internal server error" message
Your request contains a syntax error, for example, a missing comma.
POST requests result in 422 Unprocessable Entity with JSON message
POST requests result in 422 Unprocessable Entity with JSON message
Your request most likely doesn't contain required parameters (like missing keywords) or query is malformed (String was provided instead of an Array).
GET SERP Analyzer search_results requests result in 404 Not found with "Not found." message
GET SERP Analyzer search_results requests result in 404 Not found with "Not found." message
The ID you specified within your request's URL is incorrect or this ID does not belong to the account with that API-key.
GET SERP Analyzer search_results requests result in 200 OK, but most or some rows contain empty Strings
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 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)
GET SERP Analyzer prominent_terms requests result in 404 Not found with "Not found." message
GET SERP Analyzer prominent_terms requests result in 404 Not found with "Not found." message
The ID you specified within your request's URL is incorrect or this ID does not belong to the account 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 lack of sufficient written content within SERP competitors.
Additional resources: