name: NewsAPI Rate Limits
description: Rate limiting rules and quotas for the NewsAPI service at newsapi.org
specificationVersion: "0.1"
url: https://newsapi.org/docs
rateLimits:
  - name: Developer Plan Daily Limit
    description: >
      Free Developer plan accounts are limited to 100 requests per day across
      all endpoints. Exceeding this quota triggers a 429 Too Many Requests
      response with error code apiKeyExhausted.
    plan: Developer
    limit: 100
    period: day
    enforcement: hard
    httpStatus: 429
    errorCode: apiKeyExhausted
  - name: Business Plan Monthly Quota
    description: >
      Business plan accounts include 250,000 requests per calendar month.
      Additional requests beyond the included quota are billed at $0.0018 each.
    plan: Business
    limit: 250000
    period: month
    enforcement: soft
    overageRate: 0.0018
    overageCurrency: USD
    overageUnit: request
  - name: Advanced Plan Monthly Quota
    description: >
      Advanced plan accounts include 2,000,000 requests per calendar month.
      Additional requests beyond the included quota are billed at $0.0009 each.
    plan: Advanced
    limit: 2000000
    period: month
    enforcement: soft
    overageRate: 0.0009
    overageCurrency: USD
    overageUnit: request
  - name: Sources Per Request
    description: >
      A single request to any endpoint may specify a maximum of 20 comma-separated
      source identifiers. Exceeding this limit returns a 400 Bad Request response
      with error code sourcesTooMany.
    limit: 20
    period: request
    enforcement: hard
    httpStatus: 400
    errorCode: sourcesTooMany
  - name: Page Size Limit
    description: >
      The pageSize parameter controls how many articles are returned per response.
      The maximum value is 100. The default is 100 for the everything endpoint
      and 20 for the top-headlines endpoint.
    limit: 100
    period: request
    parameter: pageSize
    enforcement: hard
authentication:
  - method: apiKey
    location: queryParameter
    parameterName: apiKey
    notes: Least preferred; key may appear in server logs
  - method: apiKey
    location: header
    headerName: X-Api-Key
    notes: Preferred method
  - method: apiKey
    location: header
    headerName: Authorization
    notes: Bearer prefix is optional and key is not base64-encoded
errors:
  - httpStatus: 400
    description: Bad Request — missing or misconfigured parameter
  - httpStatus: 401
    description: Unauthorized — API key missing or invalid
    errorCodes:
      - apiKeyMissing
      - apiKeyInvalid
      - apiKeyDisabled
  - httpStatus: 429
    description: Too Many Requests — rate limit exceeded
    errorCodes:
      - rateLimited
      - apiKeyExhausted
  - httpStatus: 500
    description: Server Error — internal NewsAPI error