> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aggrefine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and limits

> Status codes, the error shape, requests per second and the daily limit, and what to do on each.

## Status codes

| Status | Meaning | What to do |
| - | - | - |
| `400` | A parameter is wrong (a `limit` over 1,000, a malformed id, `gtin` or `since`): the message says which | Fix the request; asking again unchanged gives the same answer |
| `401` | Missing, wrong or revoked key | Check the `Authorization` header and the key ([Authentication](https://docs.aggrefine.com/authentication.md)) |
| `403` | The channel is over your plan's limit (a plan that ended) | Upgrade, or use a channel your plan covers |
| `404` | No such channel (or it belongs to another organization than your key's), or no such offer | Use a channel id from `GET /v1/channels`; an offer the channel no longer shows is a `404` too |
| `410` | `since` is more than 7 days ago, or the changes since it can't be given any more | Page through the channel's offers again ([Mirror a channel](https://docs.aggrefine.com/guides/mirror-a-channel.md#3-keep-within-7-days)) |
| `429` | Too many requests: over 5 a second, or your plan's daily request limit | Wait for `Retry-After` (seconds), then ask again with the same values |
| `5xx` | Something went wrong on Aggrefine's side, or the request took too long | Retry with backoff (below) |

Errors have the shape `{ "error": "message" }`. The message is for people: show it or log it, but
decide on the status code, not the text. A `5xx` may come without that shape (as plain text, say):
don't count on its body.

## When a request fails (5xx)

A `500`, `502`, `503` or `504` means the request didn't get through this time; the same request
usually works a moment later. Retry with backoff: wait a second, then two, then four and so on, up
to a minute or so between tries, and give up after a few tries until your next run.

Every request in the API is a `GET`, so every request is safe to repeat: asking again changes no
data (though it counts against your daily limit), and gives you the same page (or a newer one) for the same values. When
you mirror a channel, ask again with the same `cursor` or `since` you used; store `next_cursor` or
`next` only after you have applied its page, and a failure never makes you skip one.

## Requests per second

Each organization may make 5 requests a second, in bursts of up to 10, across all its keys. A
request over that answers `429` with `Retry-After: 1`: wait a second and try again. Paging through
a channel's offers one page after another stays well within it.

## Daily limit

| Plan | Requests per day |
| - | - |
| Free | 300 |
| Standard | No limit during the beta |

The day is the UTC day: the limit resets at 00:00 UTC. Every request with your key counts against
it, also one that answers `400` or `404` (not one refused for a limit). A request over the limit
isn't counted and answers `429` with `Retry-After`, the seconds until 00:00 UTC.

While your plan has a limit, every response carries these headers (all but a `401`, and a `429` for
the per-second limit):

| Header | Meaning |
| - | - |
| `RateLimit-Limit` | Requests allowed per UTC day |
| `RateLimit-Remaining` | Requests left today |
| `RateLimit-Reset` | Seconds until 00:00 UTC |

To size your requests, see [Requests it takes](https://docs.aggrefine.com/guides/mirror-a-channel.md#requests-it-takes).

## Pages and caching

| Limit | Value |
| - | - |
| Offers or changes per page | Up to 1,000 (`limit`, default 100) |
| Changes kept | 7 days |

Successful answers may be reused for up to five minutes (`Cache-Control: private, max-age=300`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.