​

HTTP Status Codes

​

400 Bad Request

• Incorrect date format
• Missing required parameters
• Invalid query string
• Malformed request URL

​

Example Response

{
  "detail": "Invalid date format"
}

​

How to Fix

• Use the correct endpoint.
• Check that all required parameters are included.
• Ensure dates use the YYYY-MM-DD format.
• Review the Endpoints documentation for the required request format.

​

401 Unauthorized

​

Common Causes

​

Example Response

{
  "detail": "Invalid or inactive API key"
}

​

403 Forbidden

• The project belongs to another account.
• The keyword belongs to another project.
• Your subscription doesn’t include access to the requested feature.

​

Example Response

{
  "detail": "You do not have permission to access this resource."
}

​

404 Not Found

• The project ID doesn’t exist.
• The keyword ID doesn’t exist.
• The resource has been deleted.

​

Example Response

{
  "detail": "Not found."
}

​

Tip

• GET /projects/
• GET /project-keywords-list/{project_id}/

​

429 Too Many Requests

​

Example Response

{
  "detail": "Rate limit exceeded"
}

​

How to Fix

• Wait until the next hour before making additional requests.
• Cache responses where possible.
• Use pagination for large datasets.
• Reduce unnecessary polling.

Note In some situations, rate limit errors may also be returned as a 401 Unauthorized response with a message indicating that the API key rate limit has been exceeded.

​

500 Internal Server Error

​

Example Response

{
  "detail": "Internal server error"
}

​

How to Fix

• Wait a few moments.
• Retry your request.
• If the problem continues, contact SERPtag Support.

​

Handling Errors in Your Application

​

JavaScript Example

const response = await fetch("https://serptag.com/api/projects/", {
  headers: {
    "X-API-Key": process.env.SERPTAG_API_KEY
  }
});

if (!response.ok) {
  const error = await response.json();

  switch (response.status) {
    case 401:
      console.error("Authentication failed.");
      break;

    case 429:
      console.error("Rate limit exceeded. Please retry later.");
      break;

    default:
      console.error(error.detail || "Request failed.");
  }

  throw new Error(error.detail);
}

const data = await response.json();

​

Best Practices

• Always validate user input before sending requests.
• Store your API key securely.
• Cache responses where appropriate.
• Respect the hourly rate limit.
• Handle retry logic for temporary failures.
• Log API errors to help with debugging.

​

Need Help?

• The endpoint you called.
• The HTTP status code.
• The full error message.
• A sample request (without your API key).