Skip to main content

Rate Limits & Pagination

Rate Limits​

The TokPortal API allows 120 requests per minute per API key. The limit uses a token bucket algorithm that refills continuously, so you do not need to wait for a fixed window to reset.

Rate Limit Response​

When you exceed the limit, the API returns a 429 Too Many Requests response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please slow down.",
    "details": {
      "retry_after_seconds": 2
    }
  }
}

Best Practices​

  • Check retry_after_seconds in the error response and wait before retrying.
  • Use exponential backoff — if you receive consecutive 429s, increase the wait time between retries.
  • Spread requests evenly rather than sending them in bursts. The token bucket refills at approximately 2 tokens per second, so a steady rate of 2 req/s is sustainable.
  • Use separate API keys for independent services to isolate rate limits.

Pagination​

All list endpoints support pagination via query parameters.

Query Parameters​

ParameterDefaultMaxDescription
page1—The page number to retrieve (1-indexed).
per_page25100Number of items per page.

Example Request​

curl -X GET "https://app.tokportal.com/api/ext/bundles?page=2&per_page=50" \
  -H "X-API-Key: tok_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response Format​

Paginated responses include a pagination object alongside data:

{
  "data": [
    { "id": "bnd_abc123", "status": "published" },
    { "id": "bnd_def456", "status": "configuring" }
  ],
  "pagination": {
    "page": 2,
    "per_page": 50,
    "total": 137,
    "total_pages": 3
  }
}

Iterating Through All Pages​

async function fetchAllBundles(apiKey: string) {
  const results = [];
  let page = 1;

  while (true) {
    const res = await fetch(
      `https://app.tokportal.com/api/ext/bundles?page=${page}&per_page=100`,
      { headers: { "X-API-Key": apiKey } }
    );
    const { data, pagination } = await res.json();

    results.push(...data);

    if (page >= pagination.total_pages) break;
    page++;
  }

  return results;
}

Idempotency​

For create operations (POST requests), you can include an Idempotency-Key header to safely retry requests without creating duplicate resources.

Usage​

curl -X POST https://app.tokportal.com/api/ext/bundles \
  -H "X-API-Key: tok_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: my-unique-request-id-12345" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "tiktok", "country": "US", "videos": 10 }'

How It Works​

  • The first request with a given Idempotency-Key is processed normally.
  • Subsequent requests with the same key return the original response without executing the operation again.
  • Idempotency keys are scoped to your API key and expire after 24 hours.
  • Use a unique value per logical operation (e.g., a UUID or a meaningful identifier from your system).

When to Use Idempotency Keys​

Idempotency keys are recommended for any operation that:

  • Creates a resource (bundles, video slots, edit slots)
  • Debits credits
  • Could be retried due to network timeouts or uncertain responses

This prevents accidental double-charges or duplicate resource creation.