Limits and idempotency
What the API lets you send, and how to retry an action without doing it twice.
Coming soon
The limits
| Limit | Value | Counted per | When it is hit |
|---|---|---|---|
| Every v2 read | 60 a minute | IP address | 429 rate_limited |
| One v2 path, in a burst | 25 in 2 seconds | IP address | 429 rate_limited |
| Keyed reads | 60 a minute | Your account | 429 rate_limited |
Bulk reads of your referrals: a limit over 100, or a window over 366 days | 1 a minute | Your account | 429 rate_limited |
| Actions, any | 5 a minute | Your account | 429 rate_limited |
| Actions, all creators together | 120 a minute | The whole site | 503 unavailable |
| Spend | Your daily limit | Your account, per UTC day | 429 daily_limit_reached |
| Count of one action | 10 giveaways, 20 of each period action, 10 of each case action a day | Your account, per UTC day | 429 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
spentTodayanddailyLimit, 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 send | You get |
|---|---|
| The same key and the same body, after it finished | The first answer again, with Idempotent-Replayed: true. Nothing happens a second time. |
| The same key while the first request is still running | 409 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 action | The same refusal again. Fix the cause and send it with a new key. |
The same key after the first answer was 500 internal | 409 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.