Skip to Content
CSGOWINAPI
API v2 Coming soon

Limits and idempotency

What the API lets you send, and how to retry an action without doing it twice.

Coming soon

API v2 is not open yet - every request to it answers 404 until it launches, and the details on this page may still change. Build on API v1 today - it keeps working. New keys and a one-step switch will arrive with v2.

The limits

LimitValueCounted perWhen it is hit
Every v2 read60 a minuteIP address429 rate_limited
One v2 path, in a burst25 in 2 secondsIP address429 rate_limited
Keyed reads60 a minuteYour account429 rate_limited
Bulk reads of your referrals: a limit over 100, or a window over 366 days1 a minuteYour account429 rate_limited
Actions, any5 a minuteYour account429 rate_limited
Actions, all creators together120 a minuteThe whole site503 unavailable
SpendYour daily limitYour account, per UTC day429 daily_limit_reached
Count of one action10 giveaways, 20 of each period action, 10 of each case action a dayYour account, per UTC day429 action_limit_reached

A 429 or 503 usually carries Retry-After, in seconds. When it does not, wait a minute. For the two daily limits it is the time to the next 00:00 UTC, and the error's message names that moment as a date. Wait that long before you send again.

How the daily limit is counted

  • The day is the UTC day. It resets at 00:00 UTC.
  • Only giveaways add to it, by their prize. Every other action adds 0.
  • An action is counted when it is accepted, before it runs.
  • If the site then refuses the action (a low balance, a rule), the amount goes back. If it ended unknown (see below), the amount stays counted, because the coins may have moved.
  • It is checked as a whole: two requests sent at once cannot both pass on the last coins.
  • The limit in force is the lowest of your key's limit, any lower limit support set on your account and the site's maximum. Every done action answers spentToday and dailyLimit, in coins.

Idempotency-Key

Every action needs an Idempotency-Key header: 8 to 64 characters of letters, digits, _ and -. A UUID is the easy choice. A missing or malformed one is a 400.

It exists so that a retry cannot do the same thing twice. Make a new value for every action you mean to do, and when a request fails with no answer (a timeout, a dropped connection), send the same request with the same value again. In this example, replace YOUR_END_TIME with the time entries close, from 1 minute to 31 days ahead, written as YYYY-MM-DDTHH:MM:SSZ in UTC.

curl -X POST "https://api.csgowin.com/api/v2/creators/YOUR_CODE/giveaways" \
  -H "x-apikey: YOUR_V2_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"prize":50,"winners":1,"endsAt":"YOUR_END_TIME","name":"Friday giveaway"}'

What a repeated key does

You sendYou get
The same key and the same body, after it finishedThe first answer again, with Idempotent-Replayed: true. Nothing happens a second time.
The same key while the first request is still running409 idempotency_in_progress. Wait a moment and send it again.
The same key with a different request (path or body)422 idempotency_mismatch. A different action needs a different key.
The same key after the site refused the actionThe same refusal again. Fix the cause and send it with a new key.
The same key after the first answer was 500 internal409 outcome_unknown. Do not send it again. Check on the site and contact support with the X-Request-Id of the answer.

The key belongs to your account, not to one API key, so a retry still matches after you generate a new key. An action that never finishes is marked unknown after ten minutes.

Once an action is accepted, every answer to it carries X-Request-Id: a done action, a repeat, a refusal by the site and an unknown outcome. It is the same number as actionId in the body. Quote it to support. A refusal before that (a key, a limit, a bad request) carries none.

Let tools act for you - Errors