Error Handling

GNews API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate client-side errors (such as invalid parameters, authentication issues, or malformed requests), and codes in the 5xx range indicate an error with our servers.

HTTP Status Codes

Status Code	Error Type	Description
200	Success	Everything worked as expected
400	Bad Request	The request was malformed, often due to missing or invalid parameters
401	Unauthorized	No valid API key provided or API key is invalid
403	Forbidden	You have reached your daily quota limit, the next reset is at 00:00 UTC
429	Too Many Requests	Too many requests were sent in a short time period
500	Internal Server Error	Something went wrong on our end
503	Service Unavailable	We're temporarily offline for maintenance

Error Response Format

When an error occurs, the API returns a JSON response with error details.

General error with message:

{
  "errors": [
    "<error message>"
  ]
}

When a parameter is invalid:

{
  "errors": {
    "attribute": "<error message>"
  }
}

Common Errors and Solutions

400 - Bad Request

Causes:

• Missing required parameters
• Invalid parameter values
• Malformed query syntax
• Invalid date format

Examples:

{
  "errors": {
    "q": "The query is required."
  }
}

{
  "errors": {
    "q": "The query has a syntax error (see https://docs.gnews.io/endpoints/search-endpoint#query-syntax)."
  }
}

Solutions:

• Check that all required parameters are included
• Verify parameter values match expected formats
• Review query syntax for search operators
• Ensure dates follow ISO 8601, e.g., 2025-07-18T21:32:58.500Z

401 - Unauthorized

Causes:

• Missing API key
• Invalid API key
• Expired API key

Example:

{
  "errors": [
    "Your API key is invalid."
  ]
}

Solutions:

• Verify your API key from the dashboard
• Ensure the API key is included in the apikey parameter
• Check for typos or extra spaces in your API key
• Generate a new API key if necessary

403 - Forbidden

Causes:

• Daily quota exceeded
• Subscription expired

Example:

{
  "errors": [
    "You have reached your request limit for today, the next reset will be tomorrow at midnight UTC. If you need more requests, you can upgrade your subscription here: https://gnews.io/pricing"
  ]
}

Solutions:

• Wait for quota reset at 00:00 UTC
• Upgrade to a higher plan for more requests
• Optimize your requests to use fewer API calls

429 - Too Many Requests

Causes:

• Exceeding rate limits (requests per second)
• Too many concurrent requests

Example:

{
  "errors": [
    "This request was blocked because you made too many requests on the API in a short period of time."
  ]
}

Solutions:

• Implement request throttling in your code
• Add delays between requests
• Use exponential backoff for retries
• Upgrade your plan for higher rate limits

500 - Internal Server Error

Causes:

• Temporary server issues

Solutions:

• Retry the request after a short delay
• Contact support if the problem persists

503 - Service Unavailable

Causes:

• Scheduled maintenance
• Server overload
• Temporary service disruption

Solutions:

• Wait and retry after a few minutes

Best Practices for Error Handling

1. Always Check Status Codes

fetch(url)
    .then(response => {
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return response.json();
    })
    .then(data => {
        // Handle successful response
    })
    .catch(error => {
        // Handle error
        console.error('API Error:', error);
    });

2. Monitor Your Usage

• Check your quota usage in the dashboard
• Log API responses to track error patterns
• Monitor response times and success rates

Need Help?

If you're experiencing persistent errors or need assistance with error handling:

• Contact our support team with error details and request examples
• Join our developer community for troubleshooting tips

Remember to include the full error response and your request details when seeking help.