Error Codes

Every error returned by the Openfish API is a JSON object containing a single error field:

{
  "error": "<message>"
}

The server maps errors to HTTP status codes through five internal variants:

// From openfish-clob-server error.rs
pub enum AppError {
    BadRequest(String),    // 400
    Unauthorized(String),  // 401
    NotFound(String),      // 404
    Conflict(String),      // 409
    Internal(String),      // 500
}

---

Global Errors

These responses may appear on any authenticated endpoint.

Status	Message	Cause
401	Unauthorized/Invalid api key	API key is missing, expired, or invalid
401	Invalid L1 Request headers	L1 authentication headers are malformed or the signature does not match
429	Too Many Requests	Rate limit exceeded; implement exponential backoff
500	database error	Internal database failure; retry with backoff

---

Authentication and API Keys

POST /auth/api-key

Status	Message	Cause
400	invalid OPENFISH_ADDRESS	The address header is not a valid Ethereum address
401	L1 verification failure	Signature, timestamp, or nonce does not pass L1 verification
409	API key already exists for this address and nonce	A key with this address/nonce combination already exists

GET /auth/derive-api-key

Status	Message	Cause
404	no API key found for this address and nonce	No key exists for the given address and nonce

GET /auth/api-keys

Status	Message	Cause
401	L2 authentication failure	Invalid or missing L2 auth headers

DELETE /auth/api-key

Status	Message	Cause
404	API key not found	The key does not exist or does not belong to your account

---

Builder API Keys

POST /auth/builder-api-key

Status	Message	Cause
400	builderId required	The request body is missing the builderId field
401	L2 authentication failure	Invalid or missing L2 auth headers
500	could not create builder api key	Server-side error during key creation

GET /auth/builder-api-key

Status	Message	Cause
500	could not get builder api keys	Server-side error fetching keys

DELETE /auth/builder-api-key

Status	Message	Cause
400	invalid apiKey	The apiKey query parameter is not a valid UUID
404	builder API key not found	The key does not exist or does not belong to your account

---

Order Book

GET /book

Status	Message	Cause
400	Invalid token id	The token_id parameter is missing or invalid
404	No orderbook exists for the requested token id	No market found for this token

POST /books

Status	Message	Cause
400	Invalid payload	Request body is malformed or missing required fields
400	Payload exceeds the limit	Too many token IDs in a single request

---

Order Placement

POST /order

Status	Message	Cause
400	Invalid order payload	Request body is malformed or contains invalid values
400	the order owner has to be the owner of the API KEY	Maker address does not match your API key
400	'{address}' address banned	The address has been banned from trading
400	'{address}' address in closed only mode	The address is restricted to closing positions only

POST /orders (batch)

All errors from POST /order apply, plus:

Status	Message	Cause
400	Too many orders in payload: {N}, max allowed: {M}	Batch exceeds the maximum order count per request

---

Order Processing Errors

These errors pass initial validation but fail during matching engine processing.

Status	Message	Cause
400	invalid post-only order: order crosses book	A maker-only order would immediately match; adjust the price
400	order {id} is invalid. Price ({price}) breaks minimum tick size rule: {tick}	Price does not align with the market’s tick size
400	order {id} is invalid. Size ({size}) lower than the minimum: {min}	Order size below market minimum
400	order {id} is invalid. Duplicated.	Duplicate order submission
400	not enough balance / allowance	Insufficient USDC.e balance or token allowance
400	invalid nonce	Order nonce already used or invalid
400	invalid expiration	Expiration timestamp is in the past
400	order couldn't be fully filled. FOK orders are fully filled or killed.	Fill-or-Kill order could not be completely filled
400	no orders found to match with FAK order.	Fill-and-Kill order found no matching orders

---

Order Cancellation

DELETE /order

Status	Message	Cause
400	Invalid order payload	Request body is malformed
400	Invalid orderID	The order ID is not a valid format

DELETE /orders (batch)

Status	Message	Cause
400	Too many orders in payload, max allowed: {N}	Too many IDs in a single cancellation request

---

Builder Orders

POST /builder/order

Status	Message	Cause
400	OPENFISH_BUILDER_ID header required	The OPENFISH_BUILDER_ID header is missing or empty
400	invalid JSON: {details}	Request body is not valid JSON
400	missing 'order' field	The order key is missing from the request body

POST /builder/cancel

Status	Message	Cause
400	OPENFISH_BUILDER_ID header required	Missing builder attribution header
400	invalid JSON: {details}	Request body is not valid JSON

---

RFQ (Request for Quote)

POST /rfq/request

Status	Message	Cause
400	tokenId and size required	Missing or zero-value token ID or size

POST /rfq/quote

Status	Message	Cause
400	valid rfqId required	The rfqId is missing or not a valid UUID
400	price required	Missing or unparseable price
400	RFQ not found, expired, or already filled	The RFQ is no longer open

POST /rfq/accept

Status	Message	Cause
400	rfqId or quoteId required	Neither identifier was provided
400	RFQ not found or not owned by you	The RFQ does not belong to the authenticated user
404	no valid quotes available	No non-expired PENDING quotes exist for this RFQ
404	quote not found, expired, or already processed	The selected quote is no longer valid

---

Pricing and Market Data

GET /price, GET /midpoint, GET /spread

Status	Message	Cause
400	Invalid token id	The token_id parameter is missing or invalid
400	Invalid side	The side parameter must be BUY or SELL
404	No orderbook exists for the requested token id	No market found

---

Status Code Reference

Status	Meaning	Common Causes
400	Bad Request	Invalid parameters, malformed payload, business logic violation
401	Unauthorized	Missing or invalid API key, bad HMAC signature
404	Not Found	Market does not exist, order not found, token ID not recognised
409	Conflict	Duplicate resource (e.g., API key already exists)
429	Too Many Requests	Rate limit exceeded; implement exponential backoff
500	Internal Server Error	Unexpected server error; retry with backoff

---

Next Steps

• Contract Addresses — Smart contract addresses on Polygon.
• Architecture — Openfish system design and service layout.