Error Codes — YoorQuezt Docs

Error Format

All API errors return a consistent JSON structure:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or expired",
    "status": 401
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created (originator registered, bundle submitted)
400	Bad Request — invalid parameters
401	Unauthorized — invalid or missing API key
403	Forbidden — key lacks required tier
404	Not Found — tx, bundle, or intent not found
429	Too Many Requests — rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Common Error Codes

Code	Description	Resolution
`invalid_api_key`	API key is invalid or expired	Check key and register a new one
`rate_limit_exceeded`	Too many requests per second	Implement backoff or upgrade tier
`chain_not_supported`	Chain not available	Check /healthz for available chains
`bundle_reverted`	Bundle simulation reverted	Check calldata and gas limits
`intent_expired`	Intent deadline passed	Submit a new intent
`solver_suspended`	Solver has too many penalties	Contact support
`insufficient_balance`	Not enough ETH for gas	Fund your wallet
`tx_already_known`	Transaction already in mempool	Use the existing tx hash

Error Handling Example

async function protectedSend(tx: string) {
  const res = await fetch(
    "https://rpc.yoorquezt.io/v1/rpc/ethereum-sepolia",
    {
      method: "POST",
      headers: {
        "X-API-Key": "yq_test_abc123",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        jsonrpc: "2.0",
        method: "eth_sendRawTransaction",
        params: [tx],
        id: 1,
      }),
    }
  );

  if (!res.ok) {
    const { error } = await res.json();
    switch (error.code) {
      case "rate_limit_exceeded":
        await sleep(1000);
        return protectedSend(tx);
      case "chain_not_supported":
        throw new Error("Chain unavailable");
      default:
        throw new Error(error.message);
    }
  }

  return res.json();
}