Surfer API Troubleshooting

Nous sommes en train de traduire le centre d'aide de Surfer en français. Pour l'instant, cette page est disponible en anglais.

Nos utilisateurs francophones pourront bientôt explorer tous les guides, tutoriels et ressources en français — restez à l'écoute !

Reference Table:

Possible issues you might come across while using the 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 reached the usage limit for that particular tool in your current billing period.

• 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.

11. ANY request leading to 429 Too Many Requests

This simply means you’ve exceeded the rate limit. All endpoints have a default limit of 10 requests/sec, except for SERP batch: 10 requests/min. Wait and retry. If you’re consistently calling this, review your request frequency or contact Support.

12. POST leading to 406 Not Acceptable

Note that this is for v2 only. The response format you requested isn’t available. This usually means an Accept header was included with an unsupported value. Remove it or set it to application/json.

13. ANY request → 404 Not Found (wrong base URL)

Mind that this is different from the SERP-specific 404 above. If you’re getting a 404 on a non-SERP endpoint, your base URL is likely wrong. Make sure you’re hitting:

• v1: https://app.surferseo.com/api/v1/

• v2: https://app.surferseo.com/api/v2/

Not api.surferseo.com or surferseo.com/api/… or any other variation.

14. POST → 413 Content Too Large

Your request body exceeds the size limit. Most common on the AI Detector (max 100k characters) and Humanizer (minimum 128 characters, but very large inpts may be rejected). Trim your input and try again.

15. ANY request → 415 Unsupported Media Type

Your request is using an unsupported Content-Type header. All requests must use Content-Type: application/json.

Additional resources:

Surfer API Introduction

Surfer API Documentation (v1)

Surfer API Documentation (v2)

Surfer API Examples of Use