Error Handling

Our API categorizes errors into two different and very distinct types:

• Client Side Errors --> 4xx errors
• Server Side Errors --> 5xx errors

Failed Requests

Please note that we do not charge the user for the execution of failed requests. Only successful requests count toward your credit budget.

Client Side Errors

When a request first lands at our servers, we make a number of security, authentication and data validation checks. If any of these fail, a Client Side Error is generated with a message detailing the error that took place.

An example would be forgetting to set the X-API-KEY header which is required to authenticate the request. Another example would be providing invalid input data to one of the endpoint parameters.

Bad Route

// Request curl -L 'https://api.serpgrid.dev/some/bad/url' // Server Response { "http_code": 404, "http_message": "Not Found", "timestamp": 1752620748, "execution": 5, "message": "Requested route was not found", "payload": [] }

Missing API Key

// Request curl -L 'https://api.serpgrid.dev/v1/keywords/bulk' // Server Response { "http_code": 401, "http_message": "Unauthorized", "timestamp": 1752621110, "execution": 10, "message": "X-API-KEY header was not provided with the correct format", "payload": [] }

Server Side Errors

Server Side Errors often indicate incorrect execution of the request based on the provided user input. In order to protect our servers from malicious use, we have strict rules in place that halt execution. All of these requests are responded to with a 500 HTTP code. If you encounter such an error, you may report it to us for closer inspection using one of our customer support channels: Contact Page, Twitter, or Discord.

HTTP Codes