Errors and rate limits
Our API answers an error with a standard HTTP status and a short JSON body that says what went wrong. Fix the request before you retry a 400, 401, 403 or 404. Retry a 429 or a 5xx after a wait that grows each time.
On this page
Errors come back as JSON with statusCode and message, and most also carry error:
{
"statusCode": 401,
"message": "Invalid or expired API key",
"error": "Unauthorized"
}When a 400 comes from a field check, message is a list with one line per problem. Log the whole body: the message is usually the fix.
| Status | What it means | What to do |
|---|---|---|
| 400 | A parameter or body field failed a check. On advertiser events, also any field the API doesn’t know. | Read message, fix the request, then send it. Don’t retry it unchanged. |
| 401 | No key, a mistyped key, a revoked or expired key, or a publisher account that isn’t active. | See the key messages below. |
| 403 | The key is valid, but this account can’t use the route. | Read message. Email us if it doesn’t say why. |
| 404 | The route, or the item in it, doesn’t exist for your account, such as an offer you can’t run. | Check the path and the ID. |
| 429 | Too many requests from one address in a short time. | Wait, then retry with a growing wait. |
| 5xx | Something failed on our side. | Retry with a growing wait. If it keeps happening, email us the time and the request. |
On the offer calls, a query parameter we don’t recognize is dropped without an error. If a filter seems to do nothing, check its spelling against the Offer API reference.
| Message | Status | Where | What to do |
|---|---|---|---|
Missing x-api-key header | 401 | Network API | Send your key as x-api-key: ak_.... |
Invalid or expired API key | 401 | Offer API, Network API | Check the key in API Keys: a revoked or removed key is no longer listed; an older publisher key past its date reads expired under Status; networks check whether Expires has passed. |
Partner account is not active | 401 | Offer API | The publisher account is restricted (“partner” is an older name for a publisher account). Email us. |
Invalid API key | 401 | Advertiser events | The key doesn’t start with ak_, isn’t an advertiser key or was revoked. Mint a new one on the campaign. |
Your account is currently restricted. | 403 | Network API | Email us. |
Your account is pending approval. | 403 | Network API | Your network account hasn’t been activated yet. Email us if you expected it to be. |
Publisher keys made since 24 August 2026 never expire; older ones show their date under Expires. Network keys expire, 90 days after you generate them by default, and an expired key answers 401 on every call. To put the next key live before that date you need room for two keys: the key list shows Used against your limit, and at one, ask us to raise it first. Where keys come from: hosts and keys.
An advertiser event that we accept but don’t charge still gets a success response. The reason is in the status field of the body: duplicate, missing_attribution, invalid_event, outside_window, campaign_paused, insufficient_balance or rejected. Read status on every response, not only the HTTP code. What each one means: advertiser events.
We limit how many requests one address or one account can make in a short time. We don’t publish the numbers, and they can change. You’ll see a limit as one of these:
- 429 with
Too many requests, on sign-in, sign-up, invite links, password and secret changes, and the public top offers list. - 400 with a message that starts
Rate limit exceeded, on advertiser events and install matching.
When you hit one:
- Wait, then retry. Double the wait after each failed try, and stop after a few.
- Advertisers: send each event as it happens, not in a nightly batch. A retry with the same
eventIdcomes back asduplicate, so retrying is safe. - Publishers: the offer list changes as caps fill and offers end. Refresh it on a schedule, not on every tap.
These are the requests that go the other way, from us to your server.
- We send a GET and wait for your answer. Answer with any 2xx status, best of all 200.
- Publisher postbacks: if your server doesn’t answer, or answers 5xx or 429, we try again a few times within seconds; any other 4xx is final. Network postbacks are sent once.
- The result is in Flight Recorder. Publishers see Your postback delivery (Attempted, HTTP status, Error), and Copy request copies the masked URL we called. Networks see Network Delivery Response, with the Masked URL.
- After the last try the delivery reads
failed. Publishers: once your server is fixed, send us the action IDs: our team can send a failed credit from the Offer API or a link again, under the sameaction_id, so your dedupe still works.
How to answer and verify them: postback reference. When one doesn’t arrive at all: Postback not firing or never arrives.