# 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](https://t.me/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](https://t.me/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](https://docs.covr.markets/reference/gateway/rfq-lifecycle.md#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](https://docs.covr.markets/reference/gateway/rfq-lifecycle.md#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](https://docs.covr.markets/reference/gateway/messages.md#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`.

---

Source: https://docs.covr.markets/reference/gateway/errors · Part of covr Docs, https://docs.covr.markets/llms.txt
