API v2 Coming soon
Errors
One envelope, a stable code, and what to do about it.
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.
Every error has the status of its code and the same body. Branch on code, which is stable. The message is for a person and may change. A 200 never carries an error.
{ "error": { "code": "invalid_key", "message": "the key is not a live API v2 key of this code" } }The object has only these two fields. For the two daily limits the message says when they reset (the next 00:00 UTC), and Retry-After gives the same moment in seconds. Other answers that ask you to wait usually carry Retry-After too.
| Status | Code | When | What to do |
|---|---|---|---|
| 400 | bad_request | The request does not match the operation's schema, the site refused it with its own reason, or the Idempotency-Key is missing or malformed. | Read the message, fix the request and send it again. After a refusal by a site rule, use a new Idempotency-Key. |
| 400 | unknown_currency | A read was asked for its amounts in a currency other than COINS, USD, EUR or GBP. | Send one of those codes in capitals, or leave currency out for coins. |
| 401 | missing_key | There is no x-apikey header. | Send the key in the x-apikey header. |
| 401 | legacy_key | The key is a v1 key. API v2 keys start with cgw2_. | Switch to API v2 in Profile > Affiliates > API key and use the v2 key. |
| 401 | invalid_key | The key is unknown, revoked or malformed, or the code in the path is not one of your codes. The answers are the same on purpose. | Check the key and the code. A revoked key never works again: generate a new one. |
| 403 | key_blocked | Support blocked API v2 for the account. Generating a new key does not lift it. | Contact support. |
| 403 | account_restricted | The account is banned or closed. | Contact support. |
| 403 | actions_not_enabledActions only | The key does not have "Let tools act for me" on. | Turn it on under Change acting, or generate a key with it on. Reads do not need it. |
| 403 | second_factor_requiredActions only | "Let tools act for me" is on but the account no longer has two-factor authentication. | Set two-factor authentication up again. |
| 403 | staff_accountActions only | The key's account holds a staff role. Staff accounts cannot act through a key. | Use a creator account. |
| 404 | not_found | Nothing is there: an unknown path or id, a code with no leaderboard or giveaways, a period or case that is not yours or not on this board, or API v2 (for an action, its actions) is not open. | Check the path and the ids. |
| 404 | leaderboard_inactive | The code's leaderboard is not active. | Nothing to fix on your side. |
| 409 | idempotency_in_progressActions only | The same Idempotency-Key is still being processed. | Wait a moment and send the same request with the same key again. |
| 409 | outcome_unknownActions only | The first request with this Idempotency-Key ended in 500 internal, so it is not known whether the action happened. | Do not send it again. Check on the site and contact support with the X-Request-Id of the answer. |
| 409 | stats_not_ready | The figures for this code are still being built. | Try again later. |
| 422 | idempotency_mismatchActions only | The same Idempotency-Key arrived with a different request: another path, code, id or body. | A different action needs a different Idempotency-Key. |
| 429 | rate_limited | Too many requests in a minute, or more than 25 to one path in 2 seconds. The answer usually carries Retry-After, in seconds. | Wait that long (a minute when there is none), then continue. |
| 429 | daily_limit_reachedActions only | This action would take the day's spend over the daily limit. The message names the limit, what was spent today and when it resets. Retry-After is the time to the next 00:00 UTC. | Wait for the reset, or raise the limit in Profile > Affiliates > API key. |
| 429 | action_limit_reachedActions only | The account has made as many of this action as it may today. Retry-After is the time to the next 00:00 UTC. | Wait for the reset. |
| 500 | internal | Something failed on our side. For an action it means the outcome is unknown: the action may have happened. | For a read, try again later. For an action, do not send it again: check on the site and contact support with the X-Request-Id of the answer. |
| 503 | unavailable | The API cannot answer right now, or actions are paused site-wide for a moment. Nothing was done. The answer carries Retry-After, in seconds. | Wait that long, then try again. |
Limits and idempotency explains the 409, 422 and 429 answers of actions.