What does http_poll do when the API I poll returns 429 or a 5xx error?

Tares backs off automatically when an API you poll with http_poll returns a 429 or any 5xx error. It makes no request until the wait is over, doubles the wait from your poll interval up to an hour, and clears the backoff on the next good poll. The source’s health shows what happened and when the next try is.

How it works

The http_poll connector calls your endpoint on the source’s schedule. When a reply is an error, it reacts by status class:

• 429 or any 5xx: Tares makes no request until the wait is over. The wait starts at the poll interval and doubles each time the API keeps failing, up to a maximum of one hour.
• 429 with Retry-After: Tares uses the Retry-After value as the wait instead of the doubling schedule.
• Any other 4xx: Tares does not back off. It shows a config error on the source’s health, with the status and a slice of the reply, so you can see what the API complained about, such as a wrong URL or a rejected credential.
• Next good poll: the backoff clears and polling continues on the normal interval.

The source’s health tells you which state you are in. During a backoff it reads “rate limited by the API, next try at HH:MM”, so you see the time of the next request without checking logs.

Tares also guards the interval when you save. A poll under 10 seconds is refused on save, so a source cannot be configured to hit an API faster than that in the first place.

This behavior is part of the http_poll connector itself. You do not turn it on or tune it per source. The full connector, including authentication and how a reply becomes events, is on the HTTP API (poll) page.

Set it up

You do not configure the backoff. You set a sensible poll interval and check the health when something goes wrong.

1. Add the source. In the UI, go to Sources → Add source → HTTP API (poll), fill in the method, URL and any credential, press Discover, pick the entity key and create it. Or send the same object to POST /api/sources.
2. Set poll to 10 seconds or more. Anything shorter is refused when you save. Pick an interval the API’s limits can carry, because the backoff starts from this value.
3. Put the credential in credential, and name its header in credential_header if it is not Authorization. A wrong credential usually comes back as a 4xx, which shows as a config error rather than a backoff.

- name: weather_berlin
  connector: http_poll
  poll: 10m
  config:
    url: https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&current_weather=true
    event_type: weather
    event_time_field: current_weather.time
    id_field: current_weather.time
    text_template: 'Berlin wind {current_weather.windspeed} km/h, {current_weather.temperature} C'
    labels:
      - { name: city, const: berlin, primary: true }
      - { name: windspeed, field: current_weather.windspeed, type: number }

4. Open the source and read its health. A message that says rate limited by the API with a next try time means the backoff is running. A config error with a status and part of the reply means a 4xx other than 429 that you need to fix.
5. After you fix a config error, or after the API recovers, wait for the next poll. When it succeeds, the backoff clears on its own.

If you build monitoring from a goal, the same rules apply to any http_poll source the plan creates. The AI SRE guide shows where polled sources fit in a wider setup.

What you get

• No hammering of a struggling API. While a wait is running, Tares sends nothing, so a rate limit or an outage is not made worse by your polling.
• Respect for the API’s own instructions. A 429 with Retry-After uses the value the API gave you.
• A bounded delay. The wait never grows past an hour, so polling resumes within that time once the API is healthy again.
• Readable health. You see “rate limited by the API, next try at HH:MM” for backoffs, and a config error with the status and a slice of the reply for other 4xx errors. You can tell a temporary limit from a mistake in your setup.
• Automatic recovery. The next good poll clears the backoff with no action from you.
• Protection at save time. A poll interval under 10 seconds never becomes a running source.

Triggers that watch the source simply see events resume when polling resumes. Events are stored per poll, so a gap in the data matches the period of the backoff.

When something else fits

If the system can call Tares itself, use the webhook connector instead. Nothing is polled, so there is no rate limit to back off from. If your data lives in Prometheus, Postgres or Loki, use the dedicated connector for it rather than polling its HTTP API, and see the HTTP API (poll) page when the API has no connector of its own.

Related