API referenceReference
Errors and limits
What comes back when something is wrong, and how often you may ask.
Statuses
Errors come back as JSON with an error field. The status is the part worth branching on.
| Status | Means |
|---|---|
| 400 | The body or query did not validate. The error field carries the specific issues. |
| 401 | Missing, malformed, unknown or revoked key. All four answer identically, on purpose. |
| 403 | The key is valid but lacks the scope for this route. Fix the key, not the call. |
| 404 | No such campaign, creator or link on this account. A 404 never distinguishes 'does not exist' from 'is not yours'. |
| 409 | That handle on that platform is already enrolled under a different externalId. |
| 429 | Rate limited. See retry-after. |
A replayed idempotent request is not an error. Re-opening a campaign or re-enrolling a creator returns 200 with the existing object rather than 201, check the status, or created on an enrolment, if you need to tell them apart.
Rate limits
600 requests per minute per key. Every response carries the budget; a 429 carries how long to wait.
| Header | Means |
|---|---|
| x-ratelimit-limit | Requests allowed in the current minute. |
| x-ratelimit-remaining | How many of them are left. |
| retry-after | On a 429 only: seconds until the window resets. Exact rather than a guess, because the window is wall-clock aligned. |
Honour retry-after and retry once. The limit is there to catch a runaway loop rather than to ration normal use, so if you are reaching it in ordinary traffic, say so and it moves.