# 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.
