Errors

This API uses conventional HTTP response codes to indicate the success or failure of API requests.

HTTP Status Codes

In general:

• Codes in the 2xx range indicate success
• Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, endpoint not found, etc.)
• Codes in the 5xx range indicate an error with our API (these are rare)

Common Status Codes

Rate Limit Errors

When the rate limit is exceeded, an error is returned with the status "429 Too Many Requests", using the same detail envelope as every other error:

{
  "detail": "Too many requests"
}

Check the response headers for rate limit information:

• x-ratelimit-requests-limit - Maximum requests allowed
• x-ratelimit-requests-remaining - Requests remaining in current window

Error Response Format

Errors are returned in a consistent JSON format: a single detail key holding a human-readable message.

{
  "detail": "Human-readable error message"
}

Examples of real responses:

Error Handling

Always check the response status and handle errors appropriately:

try {
  const response = await fetch(url, {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY'
    }
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.detail);
  }
  
  const data = await response.json();
  // Handle successful response
} catch (error) {
  console.error('API Error:', error.message);
}

import requests

try:
    response = requests.get(
        'https://api.serply.io/v1/search/q=query',
        headers={'X-Api-Key': 'YOUR_API_KEY'}
    )
    response.raise_for_status()
    data = response.json()
    # Handle successful response
except requests.exceptions.HTTPError as e:
    error = e.response.json()
    print(f"API Error: {error.get('detail', e)}")