Gateway reference
Errors
This page lists every refusal a desk can get from the gateway: close codes, handshake refusals, JSON-RPC errors per method, and HTTP errors from GET /api/rfqs/<id>. Each entry says what it means and what to do.
How errors arrive
| Kind | Where | Shape |
|---|---|---|
| Handshake refusal | Any upgrade | HTTP status, or a dropped connection. No WebSocket is opened. |
| Close code | Any socket | A WebSocket close frame with a code and a short reason, or an abnormal closure. |
| JSON-RPC error | /maker, or a feed you wrote to | {"jsonrpc":"2.0","id":...,"error":{"code":-32602,"message":"..."}} |
| HTTP error | GET /api/rfqs/<id> | Status code and {"error":"..."} |
Every JSON-RPC error has code -32602. Tell them apart by message. id is the request's id, or null if the frame could not be read as JSON-RPC.
Replaced text
The gateway never sends text generated by its runtime or libraries, such as a failed property read or a JSON parser message. You get a fixed text instead:
| You get | When |
|---|---|
invalid JSON request | The frame is not valid JSON. |
invalid request | A runtime error inside the gateway's checks, not a policy refusal. The desk-reachable causes are: in bid_intent, a market or wallet that is not a string; in quote, an assetAddress, usd, collateralAsset, maker or writer that is not a string, or a signature whose s is 2^255 or more. |
The network check could not complete. Please try again shortly. | A string field that must be a Solana public key is not valid base58: market or wallet in a bid intent, writer in a quote. Despite the wording, this is not a network problem. Fix the field. Do not retry the same frame. |
Policy refusals keep their exact wording, listed below.
Close codes
| Code | Reason | Meaning | What to do |
|---|---|---|---|
4401 | Unauthorized | No Authorization header, a malformed one, or a token covr does not know. Sent before the socket is subscribed or read. | Check the header format and the token. Do not retry in a loop. A new token works only after covr's next gateway restart. Otherwise: Message us on Telegram: @malviyaop. |
4403 | Asset not allowed | A feed for an asset your token does not allow. | Subscribe only to your allowed assets. To change them: Message us on Telegram: @malviyaop. |
4429 | Too many connections | Your quote key already holds 16 sockets, across all its tokens. | Close sockets you no longer use. Dead ones free within about 60 s. Then retry with backoff. |
4429 | Too many frames | This socket spent its frame budget: 100 at once, then 20 per second. Nothing more it sent is read. | Fix the sending loop. Reconnect with backoff. |
1009 | (empty) | A frame over 16 384 bytes. | Send smaller frames. A legitimate frame is under 1 KB. |
1006 | (no close frame) | The gateway terminated the socket: it did not echo the previous heartbeat ping, or more than 1 MiB was queued for it. Also seen when the gateway restarts, or when the network path fails. | Reconnect with backoff. Answer pings and read continuously. |
1002, 1007 | set by the WebSocket library | The frame broke the WebSocket protocol, or a text frame was not valid UTF-8. | Fix your WebSocket client. |
GatewayClient reports two more closes of its own, as closed events:
| Code | Reason | Meaning |
|---|---|---|
1006 | no pong within 30000 ms | The SDK's own heartbeat found the path dead. |
1008 | maker-sdk: more than 1000 events went unread; ... (socket client) | Your code stopped reading events(). The client closed itself. |
Handshake refusals
These happen before any WebSocket exists, so there is no close code.
| You see | Meaning | What to do |
|---|---|---|
HTTP 503, or the connection drops | The endpoint is at its shared connection capacity. | Retry with backoff. |
HTTP 401, or the connection drops | The path is not a desk route: wrong spelling, uppercase alias, a query string or a trailing slash. | Use exactly /maker or /rfqs/<lowercase alias>. |
| The connection drops | Too many refusals are in progress at once (32). | Retry with backoff. |
Any frame
These apply to every frame on /maker, and to anything written to a feed.
| Message | Meaning | What to do |
|---|---|---|
invalid JSON request | Not valid JSON. id is null. Changes no award. | Fix the encoder. |
invalid JSON-RPC request | Not an object with "jsonrpc": "2.0", a string id of at most 128 characters, and a string method. id is null. Also sent for a batch (array). | Fix the frame. Do not reply to award with a JSON-RPC response. |
RFQ subscription is read-only | You sent a request on a feed socket. | Send requests on /maker only. |
command unsupported: no funding, approvals or execution in sandbox | Unknown method. | Use bid_intent, quote, award_decline or rfq_note. |
Single-maker failure reporting unavailable | You sent rfq_failure. It is not part of the desk protocol. | Use award_decline or rfq_note. |
bid_intent
Listed in the order the gateway checks them. The first failing check is the one you get.
| Message | Meaning | What to do |
|---|---|---|
Sealed bid intents are unavailable | The JSON-RPC id is not an RFQ the gateway knows: a typo, or an RFQ older than 120 s. | Use the RFQ id from the feed as id. |
Maker is not registered for this asset | The RFQ's asset is outside your token's allowlist. | Bid only on your assets. |
Bid intent maker is not this connection's registered maker | params is not an object, or its maker is missing, not a string, or not the quote key your token maps to (compared case-insensitively). | Send the intent object with your own registered key. |
Ordinary V3 opening unavailable | New orders are paused for a moment while covr updates its market list. | Skip this RFQ. Bid on the next. |
Unexpected or missing bid intent field | params does not have exactly the 18 intent fields. | Send exactly the 18 fields, no id or extras. |
Auction ID mismatch | auctionId is not a UUID v4, or differs from the JSON-RPC id. | Use the RFQ id in both. |
Auction kind mismatch | kind is not "open". | Send "open". |
invalid request | market or wallet is not a string. | Copy the values from the snapshot. |
The network check could not complete. Please try again shortly. | market or wallet is a string but not a valid base58 public key. Not a network problem. | Copy the values exactly. |
market mismatch | market is not the snapshot's market. | Copy it from GET /api/rfqs/<id>. |
wallet mismatch | wallet is not the snapshot's wallet. | Copy it from GET /api/rfqs/<id>. |
Opening intent must not bind a position | position is not null. | Send null. |
Invalid chainId | Not a non-negative safe integer. | Copy from the RFQ. |
Invalid expiry | Not a non-negative safe integer. | Copy from the RFQ. |
Invalid validUntil | Not a non-negative safe integer. | Send unix seconds as a JSON number. |
Invalid option side | isPut or isTakerBuy is not a boolean. | Send false, false. |
Invalid assetAddress | Not a valid 20-byte hex address. Mixed case must be a valid checksum. | Copy the lowercase alias. |
Invalid maker | maker names your key but is written in mixed case with a wrong EIP-55 checksum. | Send it lowercase or correctly checksummed. |
Invalid usd | Same, for usd. | Copy from the RFQ. |
Invalid collateralAsset | Same, for collateralAsset. | Copy from the RFQ. |
canonical unsigned integer required | quantity, strike or price is not a plain decimal string (no sign, leading zero, decimal point or exponent). | Send decimal strings. |
integer overflow | quantity, strike or price is 2^256 or more. | Check your units. |
quantity must be positive | quantity is "0". | Copy from the RFQ. |
strike must be positive | strike is "0". | Copy from the RFQ. |
price must be positive | price is "0". | Bid a positive price, or send rfq_note. |
assetAddress mismatch | Differs from the RFQ's asset (case counts). | Copy it exactly. |
chainId mismatch | Differs from the RFQ. | Copy it exactly. |
expiry mismatch | Differs from the RFQ. | Copy it exactly. |
isPut mismatch | Differs from the RFQ. | Copy it exactly. |
isTakerBuy mismatch | Differs from the RFQ. | Copy it exactly. |
quantity mismatch | Differs from the RFQ. | Copy it exactly. |
strike mismatch | Differs from the RFQ. | Copy it exactly. |
usd mismatch | Differs from the RFQ. | Copy it exactly. |
collateralAsset mismatch | Differs from the RFQ. | Copy it exactly. |
Bid intent expired | validUntil is at or before the gateway's clock. | Check your clock and your units (seconds). |
Bid intent expires before collection closes | validUntil <= ceil(closesAt / 1000). | Use at least ceil(hardDeadline / 1000) + 60, capped at expiry. |
Bid intent validity exceeds option expiry | validUntil > expiry. | Cap it at expiry. |
Invalid signature encoding | signature is not 0x + 130 hex. | Send the 65-byte signature as hex. |
Invalid signature recovery byte | The last byte is not 1b or 1c. | Use v = 27 or 28. |
Invalid bid intent signature | The signature cannot be checked: malformed r/s, or a value that does not fit its EIP-712 type. | Re-sign with a standard EIP-712 signer. |
Bid intent signature does not match maker | It recovers to another address: wrong domain, wrong field encoding, or wrong key. | Use the market's domain and check against the golden vectors. |
premium precision loss | quantity × price is not a multiple of 10^30: the premium is not a whole USDC atom. | Round your price with exactPriceAtOrBelow. |
token amount overflow | The premium is 2^64 USDC atoms or more. | Check your units. |
Bid intent verified but not entered: this market does not list this maker yet | Practice mode. Every check above passed: your bid is well-formed and correctly signed, but covr does not list your desk on this market: today its markets list only covr's own maker. The two checks below are not run in practice mode. | Nothing. This is the expected reply for every desk today. See Practice mode. |
Auction collection closed | The bid arrived after collection closed (3 s). | Bid faster. Read the snapshot as soon as the RFQ arrives. |
Maker already bid in this auction | You already entered a bid on this RFQ. | One bid per RFQ. |
quote
unknown RFQ comes before the award check. For every message below it, a refusal sent on the socket that holds the award also passes the award to the next maker. You cannot try again. The one exception is Executable admission is already in progress: your first quote is still being admitted and keeps the award. A refusal sent on any other socket changes no award.
| Message | Meaning | What to do |
|---|---|---|
unknown RFQ | The JSON-RPC id is not an RFQ the gateway knows. | Use the RFQ id as id. |
Awarded intent signature and quote required | params does not have exactly intentSignature and quote. | Send exactly those two fields. |
Auction is still collecting | Sent before collection closed. You cannot hold an award yet. | Wait for award. |
Executable quote is not from the awarded intent | No award is current for this RFQ (you never got one, it passed on or ended, or a quote was already admitted), or intentSignature is not the current award's signature. In a rare race it also means the award window ended between the gateway's checks. | Quote only for an award you hold, with its intent's signature, before awardUntil. |
Executable ordinary quote is not from the awarded transport | You sent the quote on a different socket from the one holding the award. | Quote on the socket that sent the bid. |
Ordinary V3 quote admission unavailable | The quote could not be admitted now: the gateway is running 4 admissions already, new orders are paused, the gateway is stopping, your socket closed, awardUntil passed, covr's final check refused the quote or did not finish before the hard deadline, or the quote expired while it was checked. | Nothing to fix in most cases. If it repeats, check your terms against Quote admission. |
quote object required | quote is not an object. | Send the signed quote object. |
Unsupported quote schema | The field set is wrong: a missing or extra field other than signature, or only one of auctionId and writer. | Send exactly the 16 fields. |
OrdinaryV3: QuoteV2 required | quote has the older 14-field shape: every other field and signature, but no auctionId and no writer. | Add auctionId and writer, and sign the QuoteV2 type. |
Invalid auction ID | auctionId is not a UUID v4. | Use the RFQ id. |
The network check could not complete. Please try again shortly. | writer is a string but not a valid base58 public key. Not a network problem. | Copy the snapshot's wallet. |
canonical unsigned integer required | nonce, price, quantity or strike is not a plain decimal string. | Send decimal strings. |
integer overflow | nonce or strike is 2^64 or more, or price is 2^128 or more. | Check your units. |
OrdinaryV3: nonce, price or e18 quantity mismatch | nonce is the reserved 2^64 - 1, price is "0", or quantity differs from the RFQ. | Fix that field. |
OrdinaryV3: quote identity or side mismatch | writer is not the customer wallet, an alias is wrong, chainId is wrong, or isPut / isTakerBuy is true. | Copy them from the snapshot and the awarded intent. |
OrdinaryV3: quote time or strike mismatch | strike or expiry differs from the market, or validUntil is not a positive integer at or before expiry. | Copy strike and expiry. Cap validUntil at expiry. |
OrdinaryV3: signature length | signature is missing, or is not 0x + 130 hex. | Send the 65-byte signature as hex. |
OrdinaryV3: signature recovery byte | The last byte is not 1b or 1c. | Use v = 27 or 28. |
OrdinaryV3: fractional USDC obligation | The premium is not a whole number of USDC atoms. | Quote the awarded price. Bid only exact prices. |
OrdinaryV3: USDC obligation overflow or zero | The premium is zero or 2^64 USDC atoms or more. | Check your units. |
invalid request | assetAddress, usd, collateralAsset, maker or writer is not a string, or the signature's s is 2^255 or more. | Fix the encoder. Use a low-s signer. |
OrdinaryV3: quote signature signer mismatch | The signature does not recover to maker. | Sign the QuoteV2 in the market's domain with your quote key. |
Ordinary auction identity | auctionId is a valid RFQ id, but not this RFQ's. | Use the awarded RFQ's id. |
Unlisted ordinary maker | maker is not the quote key your token maps to. | Quote with your own key. |
Ordinary quote review deadline | validUntil is at or before the gateway's clock, or more than 60 s after it. | Use about now + 55, capped at expiry. |
Ordinary V3 nonce already used | The gateway already admitted a different quote of yours with this nonce, and it is still live. | Never reuse a nonce. |
Auction is closed | A race only: the hard deadline passed on the gateway's internal timer between its earlier checks and the start of admission. A quote after awardUntil normally gets Ordinary V3 quote admission unavailable, and one after an admitted quote gets Executable quote is not from the awarded intent. | Answer sooner. |
Executable admission is already in progress | You sent another quote while your first one is still being admitted. | Send one quote per award and wait for its reply. |
Executable quote does not match awarded intent | price differs from the awarded intent's price. | Quote exactly your bid price. |
Ordinary V3 quote publication unavailable | The quote passed every check, but the gateway could not publish it to the customer. Rare. | Treat the signed quote as live until validUntil. |
award_decline
| Message | Meaning | What to do |
|---|---|---|
Auction is still collecting | Sent before collection closed. | Wait for award. |
Maker is not the current award | The decline was not accepted. Causes: unknown RFQ; no current award (never yours, passed on, ended, or already quoted); the award is held by another socket; params is not exactly {intentSignature}; or intentSignature is not the awarded intent's. | If you hold the award on this socket, resend exactly {"intentSignature": "<your awarded intent's signature>"} before awardUntil. Otherwise there is nothing to decline. |
Executable admission is already in progress | You already sent a quote and it is being admitted. | Wait for the quote's reply. |
A refused award_decline never passes the award. Unlike a refused quote, it leaves you holding the award, as a silent winner, until you send a correct decline or a quote, or until awardUntil passes. The customer then gets no quote.
rfq_note
| Message | Meaning | What to do |
|---|---|---|
RFQ note requires rfqId and a known reason | params is not exactly {rfqId, reason}, or reason is not one of the five. | Send one of warming_up, fully_booked, wallet_limit, too_large, not_priced. |
Ordinary V3 RFQ unavailable | rfqId is not an RFQ the gateway knows. | Use the RFQ id from the feed. |
Maker is not registered for this asset | The RFQ's asset is outside your token's allowlist. | Note only on your assets. |
RFQ note needs a maker this market lists | Practice mode: covr does not list your desk on this market. | Nothing. Notes need a listed desk, and no other desk is listed today. |
Another maker already gave this RFQ's reason | Another maker noted this RFQ first. | Nothing. Its reason stands. |
GatewayClient.sendRfqNote refuses an unknown reason locally, before sending, with maker-sdk: unknown rfq_note reason.
RFQ snapshot read
Errors from GET /api/rfqs/<id>:
| Status | Body | Meaning | What to do |
|---|---|---|---|
200 | The snapshot | See RFQ snapshot. | |
401 | {"error":"Unauthorized"} | No token, or an unknown one. Depending on how covr routes your endpoint, also a request that is not a GET or whose path is not exactly /api/rfqs/<lowercase uuid>. | Check the header, the method and the path. |
404 | {"error":"Not found"} | Depending on how covr routes your endpoint: not a GET, or the path is not exactly /api/rfqs/<lowercase uuid> (a query string, a trailing slash, uppercase hex). This check runs before the token check. | Fix the request. |
404 | {"error":"RFQ not found"} | No such RFQ, it is older than 120 s, or its asset is outside your allowlist. | Read the snapshot as soon as the RFQ arrives. |
500 | {"error":"RFQ read failed"} | The gateway failed to build the snapshot. | Skip this RFQ. |
502 | {"error":"Gateway unavailable"} | covr's endpoint could not get an answer from the gateway within 5 s. | Skip this RFQ. Retry later reads. |
503 | {"error":"Gateway stopping"} | The gateway is restarting. | Reconnect with backoff. |
GatewayClient.getRfq turns a non-2xx answer into a GatewayError whose code is the HTTP status and whose message is the body's error. If no answer arrives within httpTimeoutMs (5 s), it rejects with maker-sdk: GET /api/rfqs/<id> timed out after 5000 ms.