Pagination, repetition and competition without surprises.
The cross-cutting rules below apply to all resources and prevent duplication, infinite loops, and fragile integrations.
Limit and offset pagination
Lists use limit from 1 to 100 and offset from zero. Continue as long as offset + data.length is less than pagination.total.
http
GET /api/v1/offers?status=approved&marketplace=amazon&limit=50&offset=100
{
"data": [ ... ],
"pagination": { "limit": 50, "offset": 100, "total": 384 },
"request_id": "req_01J..."
}Filters and search
statusFilters by the canonical state of the resource.queryTextual search; treat it as correspondence, not an identifier.marketplace / channelAccepts the provider code documented in the operation.daysMobile analytics window between 1 and 365 days.from / toWhen present, use ISO 8601 timestamps in UTC.Idempotence and safe repetition
GET, PATCH and DELETE can be repeated with the same meaning. Creations that have a documented natural key, such as offer by URL and receive by external reference, return the existing resource instead of duplicating it.
You can repeat
Network failures, 429 and 5xx errors with exponential backoff and jitter.
Confirm before
POST without natural key: query by external identifier before trying again.
Don't repeat
400, 401, 402 and 403 until correct entry, key, plan or scope.
Store request_id
It links your call to the audit and simplifies any investigation.
Size, time and limit
Maximum body128 KB
Window120 req/min
Default page30 itens
Maximum page100 itens
CodingUTF-8
Content-Typeapplication/json