GET /v1/subscriptions (reference), GET /v1/inbox for inbox subscriptions (reference), the unauthenticated GET /health (reference) and your own receiver’s logs.
400 when creating a subscription
The body failed validation and nothing was saved. The usual causes:
- Impossible range.
{"gt": "10", "lt": "5"}can never match. Equal endpoints are allowed only when both are inclusive:{"gte": "10", "lte": "10"}is fine,{"gt": "10", "lte": "10"}is not. - Unknown filter or operator. Only the fields the type declares in
GET /v1/subscriptions/definitionsand onlygt,gte,lt,lteare accepted — noeq, no$gt, no nested paths.priceCross,cohortBiasOpposition,liquidationRiskCross,liquidationExposureandliquidationMaptake no filters at all. - A number that is not a decimal string.
1.5must be"1.5"; exponent notation,NaN, infinity and1/2are rejected; the maximum length is 128 characters. - Unknown type or argument. Check the spelling against the definitions;
usersent both at the top level and insideargsis also a400. - A missing required argument.
useron the four by-user types,coinandthresholdonpriceCross(a positive decimal string),coinon the four cohort bias types, pluscohortoncohortBiasFlip,cohortBiasOppositionandcohortBiasMove,otherCohortoncohortBiasOppositionandpointsoncohortBiasMove. On the liquidation risk types:userandliquidationDistancePctonliquidationRiskCross,userandpointsonliquidationRisk,coin,priceMovePctandminNotionalonliquidationExposure,coinandpriceChangePctonliquidationMap. - A cohort bias argument out of range. A
cohortthat does not belong to the chosentierType(heavyweightswithpnl), the same cohort twice oncohortBiasOpposition, orpointsthat is not a decimal string above0and at most200(arguments). - A liquidation risk argument out of range.
priceMovePctthat is not above0or is above100;resetNotionalaboveminNotional;bucketsthat is not an integer string from"1"to"200", orrangethat is not one from"1"to"100"—"1.5"and"0"are refused; a threshold that is not a positive decimal string (arguments). - A bad wallet array.
args.usermay be one address or an array of 1 to 1,000; an empty array, an invalid address or more than 1,000 entries is refused, as is a creation body over 64 KiB. OnliquidationRiskCrossandliquidationRiskit is exactly one wallet: a second address is refused.
403 when creating a subscription
The type is above your plan: liquidations and liquidationsByUser need Agent, twapStatusesByUser needs Pro. The definitions endpoint only lists what your plan may create, so a type you did not see there will be refused. See Types per plan.
The other cause is an inbox subscription on Free: "deliveryMode": "inbox" needs Starter or above, because Free’s inbox holds zero messages (the inbox).
429 when creating or enabling
Your account is at its subscription allowance — tentatively 2 on Starter, 6 on Agent, 10 on Pro, 20 on Enterprise, and 0 on Free. Delete a subscription you no longer need (GET /v1/subscriptions to find it), or move up a plan. A disabled subscription does not count toward the allowance, which is why POST /v1/subscriptions/{id}/enable can be refused with 429 too. See Plan limits.
Deliveries stopped and the subscription shows disabled: true
Your URL answered 410 Gone to a delivery. That disables the subscription at once; frames matched while it is disabled are not kept. Fix whatever returned the 410, then:
429, you are at your allowance with the disabled one re-counted — delete another subscription first. A framework that answers 410 for an unknown route, or a proxy that does during a deploy, is the usual cause; make the route answer 404 or 503 instead for anything but a deliberate stop.
Nothing arrived, and the service restarted
Ordinary deliveries and their retries are kept in memory. When the webhook service restarts — a deploy, a crash — whatever was queued or waiting to retry is lost, and nothing is replayed afterwards. Your subscription is still saved and starts delivering again on the next matching frame. If your receiver was down at the same time, the frames it missed are gone from the webhook side: read the wallet’s fills from the REST API or the WebSocket to fill the gap.priceCross behaves differently: its deliveries sit in a durable outbox and survive a restart, though a crossing that happened entirely during an outage of the source cannot be reconstructed. The four cohort bias types use the same outbox; after an outage they compare the newest snapshot with the last one they saw, and the snapshots in between are not replayed. The four liquidation risk types use it too; what happened between two checks, or during an outage, is not replayed either.
Nothing arrives, and the service did not restart
- Is the subscription there and enabled?
GET /v1/subscriptions. Adisabled: truemeans a410— see above. - Do the filters match? Exact text is case-sensitive (
BTC, notbtc);sideisAfor sell andBfor buy; sizes are in the market’s base unit and prices in its quote, so aszbound of"100000"on BTC never matches. A missing or null field never satisfies a numeric filter, so aclosedPnlbound only matches fills that carry one. - Is it the right wallet?
liquidationsByUserselects the liquidated account, not the liquidator’s fills;twapSliceFillsByUseronly carries fills with atwapId. - Is it a cohort bias type? These read a stored snapshot, normally taken every 15 minutes. The first delivery of a
cohortBiassubscription follows its creation at the service’s next check, about once a minute; after it, nothing arrives before the next snapshot.cohortBiasFlip,cohortBiasOppositionandcohortBiasMovedeliver only on a change between two snapshots: the snapshot already stored when you subscribe only sets the starting state, so the next new snapshot is the first that can fire; a cohort that stays on one side never fires a flip.coinis not checked against a list of markets, so a symbol with no snapshot rows is accepted and delivers nothing (snapshot timing). - Is it a liquidation risk type? Those have their own list, below.
- Is your receiver acknowledging? Only a
2xxcounts. A200after a long handler may already have timed out on our side and been retried; answer first, process after. - Is the receiver’s queue share full? A subscription holds at most 16 slots across the fresh and retry pools; a failing receiver saturates its own share and its newest frames are dropped. Fix the receiver and the subscription resumes on its own.
- Is the service healthy?
GET /healthanswers200while the service is up, with service counts in the body (reference).
A liquidation risk subscription delivers nothing
You subscribed toliquidationRiskCross, liquidationRisk, liquidationExposure or liquidationMap and received nothing. Go through the checks above first, then these:
- Has a check run yet? The service checks about once a minute, using positions and liquidation levels as last stored. It does not follow every price tick, and a move that happens and reverses between two checks is not seen.
- Is the condition met? Nothing is sent while it is not:
liquidationRiskCrossneeds the distance to cross the threshold. Reaching it exactly is not a crossing, and a position that stays on one side fires at most once — on its first observation, if it is already on the side you asked for.liquidationRiskfires on the first observation of a position that passes yourliquidationDistancePctfilter — without a filter, its first valid observation. After that it needs a move of at leastpointspercentage points from the last notified reading, with the filter still passing.liquidationExposureneeds at leastminNotionalwithin the move. After it fires, exposure must fall strictly belowresetNotionalbefore it can fire again.liquidationMapneeds the mark to move at leastpriceChangePctfrom the reference price.
- Is it the first observation of a
liquidationMapsubscription? That one only records the reference price — no map is sent. The first map follows a later check where the mark is at leastpriceChangePctaway from it. - Is there a recent mark price tick?
liquidationExposureandliquidationMapneed a tick for the market that is less than five minutes old. Without one they send nothing — not a zero — and the check is skipped until one arrives. - Is the wallet or the market on record?
coinis not checked against a list of markets, and a wallet is not checked for positions, when you create the subscription. A symbol with no recent mark price, or a wallet with no open positions on record, is accepted and delivers nothing. A position without a usable mark or liquidation price is skipped. - Still nothing? If the conditions above hold and nothing arrives, email chat@coinversa.ai with the subscription id and what you expected.
The URL was refused
Theurl must be public HTTPS on port 443, reached without a redirect. Refused at creation:
400 reading a subscription’s secret
GET /v1/subscriptions/{id}/secret answers 400 for an inbox subscription, because it has no signing secret: nothing is POSTed, so nothing is signed. Check deliveryMode in GET /v1/subscriptions — "inbox" subscriptions are read with POST /v1/inbox/drain, not verified. If you need both a URL and the inbox for the same wallet, create two subscriptions; each takes a slot.
413 on an inbox drain
The oldest pending message does not fit the maxBytes budget you gave POST /v1/inbox/drain — the budget covers the whole JSON response, receipt and state included, and messages are never split or skipped to fit. The 413 body carries the state and requiredMaxBytes; retry with at least that value (the parameter accepts up to 4,194,304). A message is at most 1 MiB, so a budget at the maximum always fits. Nothing was deleted or skipped by the failed call. See Drain.
acknowledged: 0 on an ack
Usually nothing is wrong. acknowledged counts the rows this request removed, and acknowledgements are idempotent, so a retried {"batchId", "count"} or {"inboxIds"} that already succeeded returns 0 — the messages are gone, which is what you wanted. Three other ways to get 0:
- The prefix was already acknowledged.
countis an absolute prefix of that batch: aftercount: 5, anothercount: 5on the same receipt is a no-op, andcount: 10deletes only the next five. - The messages expired or were evicted before your ack: they are counted in
expiredTotaloroverflowDroppedTotalin the returnedstate, not inacknowledged. An old receipt cannot delete the messages that replaced them. - The ids are not this account’s, or are unknown. Explicit
inboxIdsonly ever delete your own messages; others are ignored, not errors.
400 is different: the receipt is invalid, tampered, expired (14 days) or belongs to another account, or count is outside 1 to the batch size. Drain again for a fresh batchId. See Acknowledge.
The inbox is filling up, or messages disappeared
Compare twoGET /v1/inbox snapshots. A rising expiredTotal means messages sat unacknowledged for 14 days; a rising overflowDroppedTotal means you hit your plan’s pending-message limit or the 2 GiB cap and the oldest were evicted. Both counters are cumulative and never reset. Drain and ack more often, ack what you have processed rather than leaving it, or move up a plan (the inbox). Deleting a subscription does not clear its stored messages — acknowledge them if you no longer want them.
Signature mismatch
Check your verifier against the known-answer test vector first — it isolates your code from your framework. Then, in order of how often each is the cause:- The body was re-serialised. You verified
JSON.stringify(req.body), not the bytes received. Useexpress.raw,await request.body(),request.get_data()orio.ReadAll(r.Body)on the webhook route. - Wrong signed content. It is
webhook-id + "." + webhook-timestamp + "." + body— the id first. - Wrong secret. Each subscription has its own; if one receiver serves several, look the secret up by the body’s
subscriptionId.GET /v1/subscriptions/{id}/secretreturns the current one. - A hand-rolled HMAC. Verify with a
standardwebhookslibrary for your language; it takes thewhsec_…secret as you received it and handles the key. - Hex instead of base64. The signature is standard base64, after the
v1,prefix. - Clock skew. The libraries reject a
webhook-timestampmore than five minutes from your clock. Run NTP.
Duplicate deliveries
Expected: delivery is at least once, and order is not guaranteed across workers and retries. A retry follows any failure we observed, including a timeout after your handler already succeeded. Deduplicate onwebhook-id, which is stable across the retries of one delivery, and order by seq within one source if order matters. If two different ids carry the same fill, check whether two of your subscriptions match it — each delivers on its own.
Still stuck
Email chat@coinversa.ai with the subscription id, thewebhook-id of a delivery if you have one, and what you expected. Never send your signing secret.
