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, including a missing or malformed API key
401	Unauthorized	The API key is well-formed but does not match any account
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 The Free plan is limited to 1 request per second Paid plans are limited to 10 requests per second
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
• Missing or malformed API key

Examples:

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

{
  "errors": [
    "You did not provide an API key."
  ]
}

{
  "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:

• Invalid API key
• Expired or revoked API key

Example:

{
  "errors": [
    "Invalid API Key provided."
  ]
}

Note that a request sent without an apikey parameter, or with a malformed one, returns a 400 - Bad Request with the message You did not provide an API key. rather than a 401.

Solutions:

• Verify your API key from the dashboard
• Ensure the API key is included in the apikey parameter or in the X-Api-Key header, see Authentication
• 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

try {
    const response = await fetch(url);
    if (!response.ok) {
        throw new Error(`Request failed: ${response.status}`);
    }

    const data = await response.json();
    // Handle the successful response
} catch (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.