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.

StatusMeans
400The body or query did not validate. The error field carries the specific issues.
401Missing, malformed, unknown or revoked key. All four answer identically, on purpose.
403The key is valid but lacks the scope for this route. Fix the key, not the call.
404No such campaign, creator or link on this account. A 404 never distinguishes 'does not exist' from 'is not yours'.
409That handle on that platform is already enrolled under a different externalId.
429Rate 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.

HeaderMeans
x-ratelimit-limitRequests allowed in the current minute.
x-ratelimit-remainingHow many of them are left.
retry-afterOn 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.